wl_event_queue(3)

NAME
wl_event_queue - A queue for wl_proxy object events.

SYNOPSIS

#include <wayland-client-core.h>

  Public Member Functions
void wl_event_queue_destroy (struct wl_event_queue *queue)
struct wl_event_queue * wl_display_create_queue (struct wl_display *display)
int wl_display_roundtrip_queue (struct wl_display *display, struct wl_event_queue *queue)
int wl_display_prepare_read_queue (struct wl_display *display, struct wl_event_queue *queue)
int wl_display_dispatch_queue (struct wl_display *display, struct wl_event_queue *queue)
int wl_display_dispatch_queue_pending (struct wl_display *display, struct wl_event_queue *queue)

Detailed Description

A queue for wl_proxy object events. Event queues allows the events on a display to be handled in a thread-safe manner. See wl_display for details.

Member Function Documentation

  struct wl_event_queue * wl_display_create_queue (struct wl_display * display)
Create a new event queue for this display

Parameters:
    display The display context object

Returns:
    A new event queue associated with this display or NULL on failure.

  int wl_display_dispatch_queue (struct wl_display * display, struct wl_event_queue * queue)
Dispatch events in an event queue

Parameters:
    display The display context object
    queue The event queue to dispatch

Returns:
    The number of dispatched events on success or -1 on failure

Dispatch all incoming events for objects assigned to the given event queue. On failure -1 is returned and errno set appropriately.

The behaviour of this function is exactly the same as the behaviour of wl_display_dispatch(), but it dispatches events on given queue, not on the default queue.

This function blocks if there are no events to dispatch (if there are, it only dispatches these events and returns immediately). When this function returns after blocking, it means that it read events from display's fd and queued them to appropriate queues. If among the incoming events were some events assigned to the given queue, they are dispatched by this moment.

Note:
    Since Wayland 1.5 the display has an extra queue for its own events (i. e. delete_id). This queue is dispatched always, no matter what queue we passed as an argument to this function. That means that this function can return non-0 value even when it haven't dispatched any event for the given queue.

This function has the same constrains for using in multi-threaded apps as wl_display_dispatch().

See also:
    wl_display_dispatch(), wl_display_dispatch_pending(), wl_display_dispatch_queue_pending()

  int wl_display_dispatch_queue_pending (struct wl_display * display, struct wl_event_queue * queue)
Dispatch pending events in an event queue

Parameters:
    display The display context object
    queue The event queue to dispatch

Returns:
    The number of dispatched events on success or -1 on failure

Dispatch all incoming events for objects assigned to the given event queue. On failure -1 is returned and errno set appropriately. If there are no events queued, this function returns immediately.

Since:
    1.0.2

  int wl_display_prepare_read_queue (struct wl_display * display, struct wl_event_queue * queue)
Prepare to read events from the display to this queue

Parameters:
    display The display context object
    queue The event queue to use

Returns:
    0 on success or -1 if event queue was not empty

Atomically makes sure the queue is empty and stops any other thread from placing events into this (or any) queue. Caller must eventually call either wl_display_cancel_read() or wl_display_read_events(), usually after waiting for the display fd to become ready for reading, to release the lock.

See also:
    wl_display_prepare_read

  int wl_display_roundtrip_queue (struct wl_display * display, struct wl_event_queue * queue)
Block until all pending request are processed by the server

Parameters:
    display The display context object
    queue The queue on which to run the roundtrip

Returns:
    The number of dispatched events on success or -1 on failure

Blocks until the server processes all currently issued requests and sends out pending events on the event queue.

Note:
    This function uses wl_display_dispatch_queue() internally. If you are using wl_display_read_events() from more threads, don't use this function (or make sure that calling wl_display_roundtrip_queue() doesn't interfere with calling wl_display_prepare_read() and wl_display_read_events())

See also:
    wl_display_roundtrip()

  void wl_event_queue_destroy (struct wl_event_queue * queue)
Destroy an event queue

Parameters:
    queue The event queue to be destroyed

Destroy the given event queue. Any pending event on that queue is discarded.

The wl_display object used to create the queue should not be destroyed until all event queues created with it are destroyed with this function.

Author

Generated automatically by Doxygen for Wayland from the source code.