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

[Jonas Ådahl]

On Fri, Oct 02, 2015 at 01:36:20PM -0700, Bryce Harrington wrote:
> 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?

I expect it has to be changed/rewritten because there are some
misleading parts (like call dispatch_queue() on unrelated input). That
is why I removed it for now, with the plan to add a section about
external main loop integration elsewhere later.


Jonas

> 
> > 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