From a8246a9f0f60d83755be14e7fec2b0683a09f647 Mon Sep 17 00:00:00 2001 From: Alexandros Frantzis Date: Thu, 26 May 2022 12:05:15 +0300 Subject: [PATCH] client: Document best practices for event queue changes Document the proper way to deal with event queue changes, in order to guarantee proper handing of all events which were queued before the queue change takes effect, especially in multi-threaded setups. Make a special note about queue changes of newly created proxies, which require the use of a proxy wrapper for thread safety. Signed-off-by: Alexandros Frantzis Suggested-by: Pekka Paalanen --- src/wayland-client.c | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/src/wayland-client.c b/src/wayland-client.c index 659c1325..3e42f702 100644 --- a/src/wayland-client.c +++ b/src/wayland-client.c @@ -2311,6 +2311,19 @@ wl_proxy_get_class(struct wl_proxy *proxy) * queued in \c queue from now. If queue is NULL, then the display's * default queue is set to the proxy. * + * In order to guarantee proper handing of all events which were queued + * before the queue change takes effect, it is required to dispatch the + * proxy's old event queue after setting a new event queue. + * + * This is particularly important for multi-threaded setups, where it is + * possible for events to be queued to the proxy's old queue from a + * different thread during the invocation of this function. + * + * To ensure that all events for a newly created proxy are dispatched + * on a particular queue, it is necessary to use a proxy wrapper if + * events are read and dispatched on more than one thread. See + * wl_proxy_create_wrapper() for more details. + * * \note By default, the queue set in proxy is the one inherited from parent. * * \sa wl_display_dispatch_queue()