[PATCH 1/2] doc: Clarify the interaction of dispatch{, _queue, _pending}()

[Ander Conselvan de Oliveira]

From: Ander Conselvan de Oliveira <ander.conselvan.de.oliveira at intel.com>

Clarify on what cases each of the dispatching functions may block and
also clarify what is the main thread.
---
 src/wayland-client.c |   40 ++++++++++++++++++++++++++++++++++++++--
 src/wayland-client.h |   30 +++++++++++++++++++-----------
 2 files changed, 57 insertions(+), 13 deletions(-)

diff --git a/src/wayland-client.c b/src/wayland-client.c
index 9ac4edb..89df3ba 100644
--- a/src/wayland-client.c
+++ b/src/wayland-client.c
@@ -824,6 +824,11 @@ err_unlock:
  * Dispatch all incoming events for objects assigned to the given
  * event queue. On failure -1 is returned and errno set appropriately.
  *
+ * This function blocks until there are events to dispatch. If calling from
+ * the main thread, this will cause data to be read from the display fd. For
+ * other threads this will block until the main thread queues events on the
+ * queue passed as argument.
+ *
  * \memberof wl_display
  */
 WL_EXPORT int
@@ -833,12 +838,20 @@ wl_display_dispatch_queue(struct wl_display *display,
 	return dispatch_queue(display, queue, 1);
 }
 
-/** Dispatch a display's main event queue
+/** Process incoming events
  *
  * \param display The display context object
  * \return The number of dispatched events on success or -1 on failure
  *
- * Dispatch the display's main event queue.
+ * This function blocks until there are events to be read from the display
+ * fd. Events are read and queued on the appropriate event queues. Finally,
+ * events on the main event queue are dispatched.
+ *
+ * \note This function may block even if there are events queued on the main
+ * queue. See \ref wl_display and \ref wl_display_dispatch_pending() for
+ * details.
+ *
+ * \note Calling this makes the current thread the main one.
  *
  * \sa wl_display_dispatch_queue()
  *
@@ -852,6 +865,29 @@ wl_display_dispatch(struct wl_display *display)
 	return dispatch_queue(display, &display->queue, 1);
 }
 
+/** Dispatch main queue events without reading from the display fd
+ *
+ * \param display The display context object
+ * \return The number of dispatched events or -1 on failure
+ *
+ * This function dispatches events on the main event queue. It does not
+ * attempt to read the display fd and simply returns zero if the main
+ * queue is empty.
+ *
+ * This may be necessary if the main thread explicit calls
+ * \ref wl_display_dispatch_queue(). In that case, that call may queue
+ * events on the main thread without dispatching them. Calling \ref
+ * wl_display_dispatch() again could block indefinitely trying to read
+ * from the connection, so, in that scenario, clients should call this
+ * function before flushing and blocking.
+ *
+ * \note Calling this makes the current thread the main one.
+ *
+ * \sa wl_display_dispatch(), wl_display_dispatch_queue(),
+ *  wl_display_flush()
+ *
+ * \memberof wl_display
+ */
 WL_EXPORT int
 wl_display_dispatch_pending(struct wl_display *display)
 {
diff --git a/src/wayland-client.h b/src/wayland-client.h
index fb9c952..f1604f6 100644
--- a/src/wayland-client.h
+++ b/src/wayland-client.h
@@ -67,17 +67,25 @@ struct wl_proxy;
  * compositor when the client calls \ref wl_display_flush().
  *
  * Event handling is done in a thread-safe manner using event queues. The
- * display has a \em main event queue where initially all the events are
- * queued. The listeners for the events queued in it are called when the
- * client calls \ref wl_display_dispatch().
- *
- * The client can create additional event queues with \ref
- * wl_display_create_queue() and assign different \ref wl_proxy objects to it.
- * The events for a proxy are always queued only on its assign queue, that can
- * be dispatched by a different thread with \ref wl_display_dispatch_queue().
- *
- * All the \ref wl_display's functions are thread-safe.
- *
+ * display has a \em main event queue where events processed by the main
+ * thread are queued. Additional threads may have their own event queues,
+ * to which certain \ref wl_proxy's are assigned. A proxy's event is
+ * always queued in its assigned queue.
+ *
+ * Calling \ref wl_display_dispatch() reads data from the display fd and
+ * makes the calling thread the main thread. Events are queued on the
+ * appropriate queues. This funcion will also dispatch the events on the
+ * main queue, i.e., the listeners for those events will be called from the
+ * main thread. Other threads dispatch the events on their queue using \ref
+ * wl_display_dispatch_queue(), causing the event handlers to be called on
+ * that thread.
+ *
+ * Calling \ref wl_display_dispatch_queue() from the main thread will also
+ * read data from the display fd, but events on the main queue won't be
+ * dispatched. In that case, those events can be dispatched without
+ * attempting to read the display fd and potentially blocking by calling
+ * \ref wl_display_dispatch_pending(). The latter function will also
+ * make the current thread the main one.
  */
 struct wl_display;
 
-- 
1.7.9.5