[PATCH wayland 7/8] client: Remove misplaced documentation about main loop intergration

[Bryce Harrington]

On Fri, Oct 02, 2015 at 05:32:58PM +0800, Jonas Ådahl wrote:
> There was documentation about how to integrate the display server file
> descriptor in the documentation about wl_display_dispatch_pending().
> This is not the right place to put it, and it also had incorrect usage
> of the API (calling wl_display_dispatch_queue() on input on an unrelated
> fd) as an example.

Rather than just drop the misplaced docs, shouldn't they be moved to a
better location?

> Signed-off-by: Jonas Ådahl <jadahl at gmail.com>
> ---
>  src/wayland-client.c | 22 ----------------------
>  1 file changed, 22 deletions(-)
> 
> diff --git a/src/wayland-client.c b/src/wayland-client.c
> index e43d19d..ca2495f 100644
> --- a/src/wayland-client.c
> +++ b/src/wayland-client.c
> @@ -1636,28 +1636,6 @@ wl_display_dispatch(struct wl_display *display)
>   * attempt to read the display fd and simply returns zero if the main
>   * queue is empty, i.e., it doesn't block.
>   *
> - * This is necessary when a client's main loop wakes up on some fd other
> - * than the display fd (network socket, timer fd, etc) and calls \ref
> - * wl_display_dispatch_queue() from that callback. This may queue up
> - * events in other queues while reading all data from the display fd.
> - * When the main loop returns from the handler, the display fd
> - * no longer has data, causing a call to \em poll(2) (or similar
> - * functions) to block indefinitely, even though there are events ready
> - * to dispatch.
> - *
> - * To proper integrate the wayland display fd into a main loop, the
> - * client should always call wl_display_dispatch_pending() and then
> - * \ref wl_display_flush() prior to going back to sleep. At that point,
> - * the fd typically doesn't have data so attempting I/O could block, but
> - * events queued up on the default queue should be dispatched.
> - *
> - * A real-world example is a main loop that wakes up on a timerfd (or a
> - * sound card fd becoming writable, for example in a video player), which
> - * then triggers GL rendering and eventually eglSwapBuffers().
> - * eglSwapBuffers() may call wl_display_dispatch_queue() if it didn't
> - * receive the frame event for the previous frame, and as such queue
> - * events in the default queue.
> - *
>   * \sa wl_display_dispatch(), wl_display_dispatch_queue(),
>   * wl_display_flush()
>   *
> -- 
> 2.4.3
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel