doc: Clarify documentation about dispatching event queues

Clarify on what cases each of the dispatching functions may block, what
is the main thread and add some real world examples.

src/wayland-client.h

@@ -66,18 +66,46 @@ struct wl_proxy;
  * representation to the display's write buffer. The data is sent to the
  * 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().
+ * 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.
  *
- * 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().
+ * 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.
  *
- * All the \ref wl_display's functions are thread-safe.
+ * 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;