[PATCH] client: Add acquire-fd API to avoid requiring a polling main thread

Kristian Høgsberg krh at bitplanet.net
Wed Apr 10 08:16:11 PDT 2013


The current thread model assumes that the application or toolkit will have
a thread that either polls the display fd and dispatches events or just
dispatches in a loop.  Only the 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.  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.

The solution seems pretty straightforward: just let all threads read
from the fd.  The main-thread restriction was introduced to avoid a
race, however.  Simplified, main loops will do 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_acquire_fd(struct wl_display *display);

which returns the display fd and blocks any thread trying to read from
the fd.  Calling wl_display_dispatch() will read events, release the fd
and the dispatch events.  Alternatively,  if after acquiring and polling
the fd, a thread decides to not call wl_display_dispatch() after all,
the fd can be released by calling wl_display_release_fd().  This is
typically useful when poll returns without data on the fd, eg in case of
timeout.

The client library starts out in the legacy mode, where we assume
the dedicated event thread.  Calling wl_display_acquire_fd() will enable
the new all-threads-can-read semantics.
---
 src/wayland-client.c | 247 ++++++++++++++++++++++++++++++++++++++++++++-------
 src/wayland-client.h |   3 +
 2 files changed, 220 insertions(+), 30 deletions(-)

This latest version adds the missing pthread_cond_destroy()s that Thiago
pointed out and cleans up the wl_display_connect_to_fd() error handling.

Kristian

diff --git a/src/wayland-client.c b/src/wayland-client.c
index 0873835..e18868e 100644
--- a/src/wayland-client.c
+++ b/src/wayland-client.c
@@ -21,6 +21,8 @@
  * OF THIS SOFTWARE.
  */
 
+#define _GNU_SOURCE
+
 #include <stdlib.h>
 #include <stdint.h>
 #include <stddef.h>
@@ -73,6 +75,10 @@ struct wl_event_queue {
 	pthread_cond_t cond;
 };
 
+enum {
+	NO_READER, VOLUNTEER_READER, LOCKED_READER, LEGACY_READER
+};
+
 struct wl_display {
 	struct wl_proxy proxy;
 	struct wl_connection *connection;
@@ -83,6 +89,11 @@ struct wl_display {
 	struct wl_event_queue queue;
 	struct wl_list event_queue_list;
 	pthread_mutex_t mutex;
+	pthread_t reader;
+	pthread_cond_t reader_cond;
+	pthread_cond_t pipe_cond;
+	int reader_pipe[2];
+	int reader_state;
 };
 
 /** \endcond */
@@ -518,6 +529,10 @@ wl_display_connect_to_fd(int fd)
 	wl_event_queue_init(&display->queue, display);
 	wl_list_init(&display->event_queue_list);
 	pthread_mutex_init(&display->mutex, NULL);
+	pthread_cond_init(&display->reader_cond, NULL);
+	pthread_cond_init(&display->pipe_cond, NULL);
+	display->reader_state = LEGACY_READER;
+	display->reader = pthread_self();
 
 	wl_map_insert_new(&display->objects, WL_MAP_CLIENT_SIDE, NULL);
 
@@ -533,14 +548,126 @@ wl_display_connect_to_fd(int fd)
 	display->proxy.refcount = 1;
 
 	display->connection = wl_connection_create(display->fd);
-	if (display->connection == NULL) {
-		wl_map_release(&display->objects);
-		close(display->fd);
-		free(display);
-		return NULL;
-	}
+	if (display->connection == NULL)
+		goto err_connection;
+
+	if (pipe2(display->reader_pipe, O_CLOEXEC) == -1)
+		goto err_pipe;
 
 	return display;
+
+ err_pipe:
+	wl_connection_destroy(display->connection);
+ err_connection:
+	pthread_mutex_destroy(&display->mutex);
+	pthread_cond_destroy(&display->reader_cond);
+	pthread_cond_destroy(&display->pipe_cond);
+	wl_map_release(&display->objects);
+	close(display->fd);
+	free(display);
+
+	return NULL;
+}
+
+/** Ensure exclusive access to display file descriptor
+ *
+ * \param display The display context object
+ * \return Display object file descriptor or -1 if another thread
+ *	locked the file descriptor.
+ *
+ * This locks the file descriptor for the display, ensuring no other
+ * threads will read from it between returning from this function and
+ * calling wl_display_dispatch().
+ *
+ * Use this function to integrate the display fd into a toolkit event
+ * loop in a race-free way.  Typically, a toolkit will call
+ * wl_display_dispatch_pending() before sleeping, to make sure it
+ * doesn't block with unhandled events.  Upon waking up, it will
+ * assume the file descriptor is readable and read events from the fd
+ * by calling wl_display_dispatch().  Simplified, we have:
+ *
+ *   wl_display_dispatch_pending(display);
+ *   poll(fds, nfds, -1);
+ *   wl_display_dispatch(display);
+ *
+ * There are two races here: first, before blocking in poll(), the fd
+ * could become readable and another thread reads the events.  Some of
+ * these events may be for the main queue and the other thread will
+ * queue them there and then the main thread will go to sleep in
+ * poll().  This will stall the application, which could be waiting
+ * for a event to kick of the next animation frame, for example.
+ *
+ * The other race is immediately after poll(), where another thread
+ * could preempt and read events before the main thread calls
+ * wl_display_dispatch().  This call now blocks and starves the other
+ * fds in the event loop.
+ *
+ * Calling wl_display_acquire_fd() ensures that no other thread will
+ * read the display fd.  This means that no events will be queued
+ * between dispatching pending events and going to sleep in the event
+ * loop and that no other thread will read from the fd when data
+ * becomes available.  Calling wl_display_dispatch() will read events,
+ * unlock the fd and then dispatch new main queue events, if any.
+ *
+ * If another thread has locked the file descriptor, this function
+ * returns -1 and errno is set to EBUSY.
+ *
+ * \memberof wl_display
+ */
+WL_EXPORT int 
+wl_display_acquire_fd(struct wl_display *display)
+{
+	char c = 0;
+	int old_state;
+
+	pthread_mutex_lock(&display->mutex);
+
+	if (display->reader_state == LOCKED_READER &&
+	    !pthread_equal(display->reader, pthread_self())) {
+		errno = EBUSY;
+		pthread_mutex_unlock(&display->mutex);
+		return -1;
+	}
+
+	old_state = display->reader_state;
+	display->reader_state = LOCKED_READER;
+	display->reader = pthread_self();
+
+	if (old_state == VOLUNTEER_READER) {
+		write(display->reader_pipe[1], &c, 1);
+		pthread_cond_wait(&display->pipe_cond, &display->mutex);
+	}
+
+	pthread_mutex_unlock(&display->mutex);
+
+	return display->fd;
+}
+
+/** Release exclusive access to display file descriptor
+ *
+ * \param display The display context object
+ *
+ * This releases the exclusive access.  Useful for canceling the lock
+ * when a timed out poll returns fd not readable and we're not going
+ * to read from the fd anytime soon.
+ *
+ * \memberof wl_display
+ */
+WL_EXPORT void
+wl_display_release_fd(struct wl_display *display)
+{
+	pthread_mutex_lock(&display->mutex);
+
+	if (display->reader_state != LOCKED_READER ||
+	    !pthread_equal(display->reader, pthread_self())) {
+		pthread_mutex_unlock(&display->mutex);
+		return;
+	}
+
+	display->reader_state = NO_READER;
+	pthread_cond_broadcast(&display->reader_cond);
+
+	pthread_mutex_unlock(&display->mutex);
 }
 
 /** Connect to a Wayland display
@@ -595,8 +722,12 @@ wl_display_disconnect(struct wl_display *display)
 	wl_map_release(&display->objects);
 	wl_event_queue_release(&display->queue);
 	pthread_mutex_destroy(&display->mutex);
+	pthread_cond_destroy(&display->reader_cond);
+	pthread_cond_destroy(&display->pipe_cond);
 	if (display->fd > 0)
 		close(display->fd);
+	close(display->reader_pipe[0]);
+	close(display->reader_pipe[1]);
 
 	free(display);
 }
@@ -847,45 +978,98 @@ dispatch_event(struct wl_display *display, struct wl_event_queue *queue)
 }
 
 static int
-dispatch_queue(struct wl_display *display,
-	       struct wl_event_queue *queue, int block)
+read_events(struct wl_display *display, struct wl_event_queue *queue)
 {
-	int len, size, count, ret;
-
-	pthread_mutex_lock(&display->mutex);
-
-	if (display->last_error)
-		goto err_unlock;
-
-	ret = wl_connection_flush(display->connection);
-	if (ret < 0 && errno != EAGAIN) {
-		display_fatal_error(display, errno);
-		goto err_unlock;
+	struct pollfd pfd[2];
+	int len, size, ret;
+	char c;
+
+	if (display->reader_state == NO_READER) {
+		/* A thread gets here when it's the first reader to
+		 * try to read and there's no LOCKED_READER.  We set
+		 * VOLUNTEER_READER and poll on the fd and the
+		 * reader_pipe, so that a locked reader can preempt if
+		 * it needs to. */
+		display->reader = pthread_self();
+		display->reader_state = VOLUNTEER_READER;
+
+		pthread_mutex_unlock(&display->mutex);
+
+		pfd[0].fd = display->fd;
+		pfd[0].events = POLLIN;
+		pfd[1].fd = display->reader_pipe[0];
+		pfd[1].events = POLLIN;
+		ret = poll(pfd, 2, -1);
+		if (pfd[1].revents & POLLIN)
+			read(display->reader_pipe[0], &c, 1);
+
+		pthread_mutex_lock(&display->mutex);
+
+		pthread_cond_signal(&display->pipe_cond);
+
+		if (ret == -1) {
+			display_fatal_error(display, errno);
+			return -1;
+		}
 	}
 
-	if (block && wl_list_empty(&queue->event_list) &&
-	    pthread_equal(display->display_thread, pthread_self())) {
+	if (pthread_equal(display->reader, pthread_self())) {
+		/* At this point we have a reader.  Either a
+		 * VOLUNTEER_READER and the fd is readable or a
+		 * LOCKED_READER which is allowed to block in
+		 * wl_connection_read(). */
 		len = wl_connection_read(display->connection);
 		if (len == -1) {
 			display_fatal_error(display, errno);
-			goto err_unlock;
+			return -1;
 		} else if (len == 0) {
 			display_fatal_error(display, EPIPE);
-			goto err_unlock;
+			return -1;
 		}
 		while (len >= 8) {
 			size = queue_event(display, len);
 			if (size == -1) {
 				display_fatal_error(display, errno);
-				goto err_unlock;
+				return -1;
 			} else if (size == 0) {
 				break;
 			}
 			len -= size;
 		}
-	} else if (block && wl_list_empty(&queue->event_list)) {
-		pthread_cond_wait(&queue->cond, &display->mutex);
-		if (display->last_error)
+
+		/* Indicate we're done by setting NO_READER and wake
+		 * up other threads waiting to read. */
+		if (display->reader_state != LEGACY_READER)
+			display->reader_state = NO_READER;
+		pthread_cond_broadcast(&display->reader_cond);
+	} else {
+		/* Some other thread signed up to read from the fd, so
+		 * just wait for the reader to do the work. */
+		pthread_cond_wait(&display->reader_cond, &display->mutex);
+	}
+
+	return 0;
+}
+
+static int
+dispatch_queue(struct wl_display *display,
+	       struct wl_event_queue *queue, int block)
+{
+	int ret, count;
+
+	pthread_mutex_lock(&display->mutex);
+
+	if (display->last_error)
+		goto err_unlock;
+
+	ret = wl_connection_flush(display->connection);
+	if (ret < 0 && errno != EAGAIN) {
+		display_fatal_error(display, errno);
+		goto err_unlock;
+	}
+
+	if (block && wl_list_empty(&queue->event_list)) {
+		if (read_events(display, queue) == -1)
 			goto err_unlock;
 	}
 
@@ -965,7 +1149,8 @@ wl_display_dispatch_queue_pending(struct wl_display *display,
  * or not. For dispatching main queue events without blocking, see \ref
  * wl_display_dispatch_pending().
  *
- * \note Calling this makes the current thread the main one.
+ * \note Calling this will release the display file descriptor if this
+ * thread acquired it using wl_display_acquire_fd().
  *
  * \sa wl_display_dispatch_pending(), wl_display_dispatch_queue()
  *
@@ -974,7 +1159,8 @@ wl_display_dispatch_queue_pending(struct wl_display *display,
 WL_EXPORT int
 wl_display_dispatch(struct wl_display *display)
 {
-	display->display_thread = pthread_self();
+	if (display->reader_state == LEGACY_READER)
+		display->reader = pthread_self();
 
 	return dispatch_queue(display, &display->queue, 1);
 }
@@ -1020,7 +1206,8 @@ wl_display_dispatch(struct wl_display *display)
 WL_EXPORT int
 wl_display_dispatch_pending(struct wl_display *display)
 {
-	display->display_thread = pthread_self();
+	if (display->reader_state == LEGACY_READER)
+		display->reader = pthread_self();
 
 	return dispatch_queue(display, &display->queue, 0);
 }
diff --git a/src/wayland-client.h b/src/wayland-client.h
index 578fa7e..2efd01c 100644
--- a/src/wayland-client.h
+++ b/src/wayland-client.h
@@ -152,6 +152,9 @@ 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_acquire_fd(struct wl_display *display);
+void wl_display_release_fd(struct wl_display *display);
+
 void wl_log_set_handler_client(wl_log_func_t handler);
 
 #ifdef  __cplusplus
-- 
1.8.1.4



More information about the wayland-devel mailing list