mirror of
https://gitlab.freedesktop.org/wayland/wayland.git
synced 2026-02-07 04:06:37 -05:00
Core Wayland window system code and protocol
3c7e8bfbb4
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. |
||
|---|---|---|
| cursor | ||
| doc | ||
| m4 | ||
| protocol | ||
| spec | ||
| src | ||
| tests | ||
| .gitignore | ||
| autogen.sh | ||
| configure.ac | ||
| COPYING | ||
| Makefile.am | ||
| README | ||
| TODO | ||
| wayland-scanner.m4.in | ||
| wayland-scanner.mk | ||
What is Wayland
Wayland is a project to define a protocol for a compositor to talk to
its clients as well as a library implementation of the protocol. The
compositor can be a standalone display server running on Linux kernel
modesetting and evdev input devices, an X application, or a wayland
client itself. The clients can be traditional applications, X servers
(rootless or fullscreen) or other display servers.
The wayland protocol is essentially only about input handling and
buffer management. The compositor receives input events and forwards
them to the relevant client. The clients creates buffers and renders
into them and notifies the compositor when it needs to redraw. The
protocol also handles drag and drop, selections, window management and
other interactions that must go through the compositor. However, the
protocol does not handle rendering, which is one of the features that
makes wayland so simple. All clients are expected to handle rendering
themselves, typically through cairo or OpenGL.
The weston compositor is a reference implementation of a wayland
compositor and the weston repository also includes a few example
clients.
Building the wayland libraries is fairly simple, aside from libffi,
they don't have many dependencies:
$ git clone git://anongit.freedesktop.org/wayland/wayland
$ cd wayland
$ ./autogen.sh --prefix=PREFIX
$ make
$ make install
where PREFIX is where you want to install the libraries. See
http://wayland.freedesktop.org for more complete build instructions
for wayland, weston, xwayland and various toolkits.