Struct wayland_client::EventQueue

pub struct EventQueue { /* fields omitted */ }

An event queue for protocol messages

Event dispatching in wayland is made on a queue basis, allowing you to organize your objects into different queues that can be dispatched independently, for example from different threads.

And EventQueue is not Send, and thus must stay on the thread on which they were created. However the Display object is Send + Sync, allowing you to create the queues directly in the threads that host them.

When a queue is dispatched (via the dispatch() or dispatch_pending() methods) all the incoming messages from the server designated to objects associated with the queue are processed sequentially, and the appropriate implementation for each is invoked. When all messages have been processed these methods return.

Thus, a typical single-queue event loop for a simple wayland app can be:

loop {
    display.flush().unwrap();
    event_queue.dispatch().expect("An error occurred during event dispatching!");
}

See EventQueue::prepare_read() if you need more control about when the connection socket is read. This will typically the case if you need to integrate other sources of event into the event loop of your application.

Methods

impl EventQueue

pub fn dispatch(&mut self) -> Result<u32>

Dispatches events from the internal buffer.

Dispatches all events to their appropriators. If no events were in the internal buffer, will block until some events are read and dispatch them. This process can insert events in the internal buffers of other event queues.

If an error is returned, your connection with the wayland compositor is probably lost.

pub fn dispatch_pending(&mut self) -> Result<u32>

Dispatches pending events from the internal buffer.

Dispatches all events to their appropriators. Never blocks, if no events were pending, simply returns Ok(0).

If an error is returned, your connection with the wayland compositor is probably lost.

pub fn sync_roundtrip(&mut self) -> Result<u32>

Synchronous roundtrip

This call will cause a synchronous roundtrip with the wayland server. It will block until all pending requests of this queue are sent to the server and it has processed all of them and send the appropriate events.

Handlers are called as a consequence.

On success returns the number of dispatched events.

pub fn get_token(&self) -> QueueToken

Create a new token associated with this event queue

See QueueToken documentation for its use.

pub fn prepare_read(&self) -> Option<ReadEventsGuard>

Prepare an concurrent read

Will declare your intention to read events from the server socket.

Will return None if there are still some events awaiting dispatch on this EventIterator. In this case, you need to call dispatch_pending() before calling this method again.

As long as the returned guard is in scope, no events can be dispatched to any event iterator.

The guard can then be destroyed by two means:

• Calling its cancel() method (or letting it go out of scope): the read intention will be cancelled
• Calling its read_events() method: will block until all existing guards are destroyed by one of these methods, then events will be read and all blocked read_events() calls will return.

This call will otherwise not block on the server socket if it is empty, and return an io error WouldBlock in such cases.