mirror of
https://gitlab.freedesktop.org/wayland/wayland.git
synced 2025-11-02 09:01:39 -05:00
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.
167 lines
7.3 KiB
C
167 lines
7.3 KiB
C
/*
|
|
* Copyright © 2008 Kristian Høgsberg
|
|
*
|
|
* Permission to use, copy, modify, distribute, and sell this software and its
|
|
* documentation for any purpose is hereby granted without fee, provided that
|
|
* the above copyright notice appear in all copies and that both that copyright
|
|
* notice and this permission notice appear in supporting documentation, and
|
|
* that the name of the copyright holders not be used in advertising or
|
|
* publicity pertaining to distribution of the software without specific,
|
|
* written prior permission. The copyright holders make no representations
|
|
* about the suitability of this software for any purpose. It is provided "as
|
|
* is" without express or implied warranty.
|
|
*
|
|
* THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
|
|
* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
|
|
* EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
|
|
* CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
|
|
* DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
|
|
* TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
|
|
* OF THIS SOFTWARE.
|
|
*/
|
|
|
|
#ifndef _WAYLAND_CLIENT_H
|
|
#define _WAYLAND_CLIENT_H
|
|
|
|
#include "wayland-util.h"
|
|
#include "wayland-version.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** \class wl_proxy
|
|
*
|
|
* \brief Represents a protocol object on the client side.
|
|
*
|
|
* A wl_proxy acts as a client side proxy to an object existing in the
|
|
* compositor. The proxy is responsible for converting requests made by the
|
|
* clients with \ref wl_proxy_marshal() into Wayland's wire format. Events
|
|
* coming from the compositor are also handled by the proxy, which will in
|
|
* turn call the handler set with \ref wl_proxy_add_listener().
|
|
*
|
|
* \note With the exception of function \ref wl_proxy_set_queue(), functions
|
|
* accessing a \ref wl_proxy are not normally used by client code. Clients
|
|
* should normally use the higher level interface generated by the scanner to
|
|
* interact with compositor objects.
|
|
*
|
|
*/
|
|
struct wl_proxy;
|
|
|
|
/** \class wl_display
|
|
*
|
|
* \brief Represents a connection to the compositor and acts as a proxy to
|
|
* the wl_display singleton object.
|
|
*
|
|
* A \ref wl_display object represents a client connection to a Wayland
|
|
* compositor. It is created with either \ref wl_display_connect() or
|
|
* \ref wl_display_connect_to_fd(). A connection is terminated using
|
|
* \ref wl_display_disconnect().
|
|
*
|
|
* A \ref wl_display is also used as the \ref wl_proxy for the \ref wl_display
|
|
* singleton object on the compositor side.
|
|
*
|
|
* A \ref wl_display object handles all the data sent from and to the
|
|
* compositor. When a \ref wl_proxy marshals a request, it will write its wire
|
|
* representation to the display's write buffer. The data is sent to the
|
|
* compositor when the client calls \ref wl_display_flush().
|
|
*
|
|
* Incoming data is handled in two steps: queueing and dispatching. In the
|
|
* queue step, the data coming from the display fd is interpreted and
|
|
* added to a queue. On the dispatch step, the handler for the incoming
|
|
* event set by the client on the corresponding \ref wl_proxy is called.
|
|
*
|
|
* A \ref wl_display has at least one event queue, called the <em>main
|
|
* queue</em>. Clients can create additional event queues with \ref
|
|
* wl_display_create_queue() and assign \ref wl_proxy's to it. Events
|
|
* occurring in a particular proxy are always queued in its assigned queue.
|
|
* A client can ensure that a certain assumption, such as holding a lock
|
|
* or running from a given thread, is true when a proxy event handler is
|
|
* called by assigning that proxy to an event queue and making sure that
|
|
* this queue is only dispatched when the assumption holds.
|
|
*
|
|
* The main queue is dispatched by calling \ref wl_display_dispatch().
|
|
* This will dispatch any events queued on the main queue and attempt
|
|
* to read from the display fd if its empty. Events read are then queued
|
|
* on the appropriate queues according to the proxy assignment. Calling
|
|
* that function makes the calling thread the <em>main thread</em>.
|
|
*
|
|
* A user created queue is dispatched with \ref wl_display_dispatch_queue().
|
|
* If there are no events to dispatch this function will block. If this
|
|
* is called by the main thread, this will attempt to read data from the
|
|
* display fd and queue any events on the appropriate queues. If calling
|
|
* from any other thread, the function will block until the main thread
|
|
* queues an event on the queue being dispatched.
|
|
*
|
|
* A real world example of event queue usage is Mesa's implementation of
|
|
* eglSwapBuffers() for the Wayland platform. This function might need
|
|
* to block until a frame callback is received, but dispatching the main
|
|
* queue could cause an event handler on the client to start drawing
|
|
* again. This problem is solved using another event queue, so that only
|
|
* the events handled by the EGL code are dispatched during the block.
|
|
*
|
|
* This creates a problem where the main thread dispatches a non-main
|
|
* queue, reading all the data from the display fd. If the application
|
|
* would call \em poll(2) after that it would block, even though there
|
|
* might be events queued on the main queue. Those events should be
|
|
* dispatched with \ref wl_display_dispatch_pending() before
|
|
* flushing and blocking.
|
|
*/
|
|
struct wl_display;
|
|
|
|
/** \class wl_event_queue
|
|
*
|
|
* \brief A queue for \ref wl_proxy object events.
|
|
*
|
|
* Event queues allows the events on a display to be handled in a thread-safe
|
|
* manner. See \ref wl_display for details.
|
|
*
|
|
*/
|
|
struct wl_event_queue;
|
|
|
|
void wl_event_queue_destroy(struct wl_event_queue *queue);
|
|
|
|
void wl_proxy_marshal(struct wl_proxy *p, uint32_t opcode, ...);
|
|
struct wl_proxy *wl_proxy_create(struct wl_proxy *factory,
|
|
const struct wl_interface *interface);
|
|
|
|
void wl_proxy_destroy(struct wl_proxy *proxy);
|
|
int wl_proxy_add_listener(struct wl_proxy *proxy,
|
|
void (**implementation)(void), void *data);
|
|
void wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data);
|
|
void *wl_proxy_get_user_data(struct wl_proxy *proxy);
|
|
uint32_t wl_proxy_get_id(struct wl_proxy *proxy);
|
|
const char *wl_proxy_get_class(struct wl_proxy *proxy);
|
|
void wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue);
|
|
|
|
#include "wayland-client-protocol.h"
|
|
|
|
struct wl_display *wl_display_connect(const char *name);
|
|
struct wl_display *wl_display_connect_to_fd(int fd);
|
|
void wl_display_disconnect(struct wl_display *display);
|
|
int wl_display_get_fd(struct wl_display *display);
|
|
int wl_display_dispatch(struct wl_display *display);
|
|
int wl_display_dispatch_queue(struct wl_display *display,
|
|
struct wl_event_queue *queue);
|
|
int wl_display_dispatch_queue_pending(struct wl_display *display,
|
|
struct wl_event_queue *queue);
|
|
int wl_display_dispatch_pending(struct wl_display *display);
|
|
int wl_display_get_error(struct wl_display *display);
|
|
|
|
int wl_display_flush(struct wl_display *display);
|
|
int wl_display_roundtrip(struct wl_display *display);
|
|
struct wl_event_queue *wl_display_create_queue(struct wl_display *display);
|
|
|
|
int wl_display_prepare_read_queue(struct wl_display *display,
|
|
struct wl_event_queue *queue);
|
|
int wl_display_prepare_read(struct wl_display *display);
|
|
void wl_display_cancel_read(struct wl_display *display);
|
|
int wl_display_read_events(struct wl_display *display);
|
|
|
|
void wl_log_set_handler_client(wl_log_func_t handler);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|