There have been a lot of questions asked lately about versioning of
interfaces and protocol objects. This addition to the documentation should
clear up some of those questions.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
The method described of alocation IDs has been wrong at least since version
1.0. This commit updates it to correspond to the way IDs are chosen in
versions >= 1.0.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
When generating HTML, don't split once we're into subjections. This
generates a single page for each protocol interface instead of the previous
separate pages for requests, events and enums.
No effect on the rest of the HTML configuration.
If wayland-scanner.pc can't be found the variables end up being set
irrespectively, leaving the user with odd compiler errors about missing
headers, etc.
wayland-scanner without arguments prints out usage. With help or --help it
waits for stdin to supply something which isn't quite as informative as
printing out the help.
This patch also moves the strcmp for args up to have all of them in one
location.
We we're using wl_event_loop_add_idle() here, but if we're failing
because of OOM, that will typically also fail. Instead, use the
existing client->error flag, which will break out of the event
handling loop and shut down the client.
Functions like wl_argument_from_va_list expect from get_next_argument,
to initialize details->type but when the signature is empty or contains
only version (like in desktop-shell-protocol.c in weston) it is left
uninitialized.
This patch fixes it, by initializing details->type with '\0' value,
signaling end of arguments.
Signed-off-by: Mariusz Ceier <mceier+wayland@gmail.com>
We can't do that there, we have to make sure it stays a valid fd until
the application calls wl_display_disconnect(). Otherwise the application
may end up poll()ing on a stale or wrong fd in case another part of the
application (or another thread) triggered a fatal error.
Getting no data from the socket is not an error condition. This may
happen in case of calling prepare_read() and then read_events() with
no other pending readers and no data in the socket. In general,
read_events() may not queue up events in the given event queue. From
a given threads point of view it doesn't matter whether events were
read and put in a different event queue or no events were read at all.
If EOF is encountered while reading from the Wayland socket, make
wl_display_read_events() return -1 so that it will be treated as an
error. The documentation for this function states that it will set
errno when there is an error so it additionally makes up an errno of
EPIPE.
If we don't do this then when the compositor quits the Wayland socket
will be become ready for reading but wl_display_dispatch will do
nothing which typically makes the application take up 100% CPU. In
particular eglSwapBuffers will likely get stuck in an infinite busy
loop because it repeatedly calls wl_display_dispatch_queue while it
waits for the frame callback.
https://bugzilla.gnome.org/show_bug.cgi?id=703892
This patch introduces wl_global_create() and wl_global_destroy() as
replacements for wl_display_add_global() and wl_display_remove_global().
The add/remove_global API did not allow a compositor to indicate
the implemented version of a global, it just took the version from
the interface meta data. The problem is that the meta data
(which lives in libwayland-server.so) can get out of sync with a
compositor implementation. The compositor will then advertise a
higher version of a global than what it actually implements.
The new API lets a compositor pass in a version when it registers
a global, which solves the problem. The add/remove API is deprecated
with this patch and will be removed.
The wl_client_add/new_object() functions sends out an NO_MEMORY error if
the allocation fails. This was convenient in a couple of places where
that was all the error handling that was needed. Unfortunately that
looks like out-of-memory isn't handled at the call site and set a bad
precedent for not cleaning up properly or not handling at all.
As we're introducing wl_resource_create() as a replacement for those two
functions, let's remove the automatic error event posting and require
the caller to do that if necessary.
This commit also introduces a new helper, wl_client_post_no_memory() to
make it possible to send NO_MEMORY events from bind where we don't have
a wl_resource.
This commit provides a layer of protection for the compositor in the form
of message version checking. We track version information in the
wl_resource and now use this version information to verify that a request
exists in that protocol version before invoking it. This way libwayland
won't accidentally invoke a request that does not exist and thereby cause
the compositor to crash.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
A new function, wl_resource_create(), lets the compositor create a
wl_resource for a given version of the interface. Passing 0 for the
object ID will allocate a new ID. The implementation, user data and
destructor can be set with wl_resource_set_implementation().
These two functions deprecates wl_client_add/new_object and the
main difference and motivation is the ability to provide a version number
for the resource. This lets the compositor track which version of the
interface a client has created and we'll use that to verify incoming requests.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
This commit adds version information to wl_message signatures and a
wl_message_get_since function to retrieve. The since version comes in the
form of a (possible) integer at the begining of the message. If the
message starts with an integer, then it specifies the "since" version of
that message. Messages present in version one do not get this "since"
information. In this way we can run-time detect the version information
for a structure on a per-message basis.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
With the work to add wl_resource accessors and port weston to use them,
we're ready to make wl_resource and wl_object opaque structs. We keep
wl_buffer in the header for EGL stacks to use, but don't expose it by
default. In time we'll remove it completely, but for now it provides a
transition paths for code that still uses wl_buffer.
Reviewed-by: Jason Ekstrand<jason@jlekstrand.net>
This format is used to specify that the key button events received are not in
relation to any key map and that the codes should be interpreted directly.
v2: Use zero for the no keymap enum value and enhance the documentation
for the enum entry.
This commit does not break ABI. It merely changes the types of some things
and adds a wl_shm_buffer_get function.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
This commit makes wl_resource_destroy automatically free all non-legacy
resource structures. Since wl_resource is now an opaque structure it
doesn't make sense for the clients to be freeing it. This checks to make
sure that it was added through wl_client_add_object or wl_client_new_object
and not wl_client_add_resource before it frees it. This way if it is a
legacy resources embedded in a structure somewhere we don't have an invalid
free.
Signed-off-by: Jason Ekstrand <jason@jlekstrand.net>
Document what we expect in terms of commit messages and coding style.
New contributors are usually unaware of this, so it is good to have a
document to point them too.
The current thread model assumes that the application or toolkit will have
one thread that either polls the display fd and dispatches events or just
dispatches in a loop. Only this main thread will read from the fd while
all other threads will block on a pthread condition and expect the main
thread to deliver events to them.
This turns out to be too restrictive. We can't assume that there
always will be a thread like that. Qt QML threaded rendering will
block the main thread on a condition that's signaled by a rendering
thread after it finishes rendering. This leads to a deadlock when the
rendering threads blocks in eglSwapBuffers(), and the main thread is
waiting on the condition. Another problematic use case is with games
that has a rendering thread for a splash screen while the main thread
is busy loading game data or compiling shaders. The main thread isn't
responsive and ends up blocking eglSwapBuffers() in the rendering thread.
We also can't assume that there will be only one thread polling on the
file descriptor. A valid use case is a thread receiving data from a
custom wayland interface as well as a device fd or network socket.
The thread may want to wait on either events from the wayland
interface or data from the fd, in which case it needs to poll on both
the wayland display fd and the device/network fd.
The solution seems pretty straightforward: just let all threads read
from the fd. However, the main-thread restriction was introduced to
avoid a race. Simplified, main loops will do something like this:
wl_display_dispatch_pending(display);
/* Race here if other thread reads from fd and places events
* in main eent queue. We go to sleep in poll while sitting on
* events that may stall the application if not dispatched. */
poll(fds, nfds, -1);
/* Race here if other thread reads and doesn't queue any
* events for main queue. wl_display_dispatch() below will block
* trying to read from the fd, while other fds in the mainloop
* are ignored. */
wl_display_dispatch(display);
The restriction that only the main thread can read from the fd avoids
these races, but has the problems described above.
This patch introduces new API to solve both problems. We add
int wl_display_prepare_read(struct wl_display *display);
and
int wl_display_read_events(struct wl_display *display);
wl_display_prepare_read() registers the calling thread as a potential
reader of events. Once data is available on the fd, all reader
threads must call wl_display_read_events(), at which point one of the
threads will read from the fd and distribute the events to event
queues. When that is done, all threads return from
wl_display_read_events().
From the point of view of a single thread, this ensures that between
calling wl_display_prepare_read() and wl_display_read_events(), no
other thread will read from the fd and queue events in its event
queue. This avoids the race conditions described above, and we avoid
relying on any one thread to be available to read events.
