Struct wayland_client::EventQueue

pub struct EventQueue<D> { /* private fields */ }

An event queue

This is an abstraction for handling event dispatching, that allows you to ensure access to some common state &mut D to your event handlers.

Event queues are created through Connection::new_event_queue(). Upon creation, a wayland object is assigned to an event queue by passing the associated QueueHandle as argument to the method creating it. All event received by that object will be processed by that event queue, when dispatch_pending() or blocking_dispatch() is invoked.

Implementations

impl<D> EventQueue<D>

pub fn handle(&self) -> QueueHandle<D>

Get a QueueHandle for this event queue

pub fn dispatch_pending(&mut self, data: &mut D) -> Result<usize, DispatchError>

Dispatch pending events

Events are accumulated in the event queue internal buffer when the Wayland socket is read using the read APIs on Connection, or when reading is done from an other thread. This method will dispatch all such pending events by sequentially invoking their associated handlers: the Dispatch implementations on the provided &mut D.

pub fn blocking_dispatch(
    &mut self,
    data: &mut D
) -> Result<usize, DispatchError>

Block waiting for events and dispatch them

This method is similar to dispatch_pending, but if there are no pending events it will also block waiting for the Wayland server to send an event.

A simple app event loop can consist of invoking this method in a loop.

pub fn sync_roundtrip(&mut self, data: &mut D) -> Result<usize, DispatchError>

Synchronous roundtrip

This function will cause a synchronous round trip with the wayland server. This function will block until all requests in the queue are sent and processed by the server.

This function may be useful during initial setup with the compositor. This function may also be useful where you need to guarantee all requests prior to calling this function are completed.

pub fn prepare_read(&self) -> Result<ReadEventsGuard, WaylandError>

Start a synchronized read from the socket

This is needed if you plan to wait on readiness of the Wayland socket using an event loop. See ReadEventsGuard for details. Once the events are received, you’ll then need to dispatch them from the event queue using EventQueue::dispatch_pending().

If you don’t need to manage multiple event sources, see blocking_dispatch() for a simpler mechanism.

pub fn flush(&self) -> Result<(), WaylandError>

Flush pending outgoing events to the server

This needs to be done regularly to ensure the server receives all your requests.

pub fn poll_dispatch_pending(
    &mut self,
    cx: &mut Context<'_>,
    data: &mut D
) -> Poll<Result<Infallible, DispatchError>>

Attempt to dispatch events from this queue, registering the current task for wakeup if no events are pending.

This method is similar to dispatch_pending; it will not perform reads on the Wayland socket. Reads on the socket by other tasks or threads will cause the current task to wake up if events are pending on this queue.

use futures_channel::mpsc::Receiver;
use futures_util::future::{poll_fn,select};
use futures_util::stream::StreamExt;
use wayland_client::EventQueue;

struct Data;

enum AppEvent {
    SomethingHappened(u32),
}

impl Data {
    fn handle(&mut self, event: AppEvent) {
        // actual event handling goes here
    }
}

// An async task that is spawned on an executor in order to handle events that need access
// to a specific data object.
async fn run(data: &mut Data, mut wl_queue: EventQueue<Data>, mut app_queue: Receiver<AppEvent>)
    -> Result<(), Box<dyn std::error::Error>>
{
    use futures_util::future::Either;
    loop {
        match select(
            poll_fn(|cx| wl_queue.poll_dispatch_pending(cx, data)),
            app_queue.next(),
        ).await {
            Either::Left((res, _)) => match res? {},
            Either::Right((Some(event), _)) => {
                data.handle(event);
            }
            Either::Right((None, _)) => return Ok(()),
        }
    }
}

Trait Implementations

impl<D> Debug for EventQueue<D>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.