Struct Queue

pub struct Queue { /* private fields */ }

An event queue.

An event queue stores events that have been sent by the compositor but whose callbacks have not yet been invoked. Invoking these callbacks is called dispatching the queue.

A connection can have many queues that can be dispatched in parallel, but the events in a single queue are always dispatched in series. That is, the callback for the next event will not start executing until after the callback for the previous event.

New queues are created by calling Connection::create_local_queue or Connection::create_queue.

Proxies attached to a queue

Each proxy is attached to a queue. This queue is determined as follows:

• When Queue::display is called, the returned proxy is attached to that queue.
• When Queue::wrap_proxy is called, the returned proxy is attached to that queue.
• When a constructor request is called on an owned proxy P, e.g. WlDisplay::sync, the returned proxy is attached to the same queue as P.
• When a constructor request is called on a borrowed proxy, e.g. WlDisplayRef::sync, the request takes a queue argument and the returned proxy is attached to that queue.

See the documentation of the proxy module for more information about proxies.

Queue ownership

Each queue is owned by a QueueOwner which is returned when you call Connection::create_local_queue or Connection::create_queue.

When a QueueOwner is dropped, it will automatically destroy some of the proxies attached to the queue. This ensures that, when the QueueOwner is dropped, all reference cycles between proxies and their event handlers are broken and no memory is leaked. (Normally these cycles are broken when a destructor request is sent or the proxy is destroyed with proxy::destroy, but for long-lived proxies, such as wl_registry, it is more convenient for this to happen automatically.)

A queue and the attached proxies should no longer be used after its QueueOwner has been dropped. Doing so might lead to panics or memory leaks.

To ensure that the QueueOwner is eventually dropped, the queue owner should never be reachable from an event handler.

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue: QueueOwner = con.create_queue(c"queue name");

    // the queue owner is stored on the stack and will be dropped when this function
    // returns
    application_logic(&queue);
}

Local and non-local queues

Each queue is either local or non-local. Local queues are created with Connection::create_local_queue. Non-local queues are created with Connection::create_queue.

Local queues have the following advantage:

• Event handlers attached to local queues do not have to implement Send.

This allows such events handlers to contain Rc<T> where the same event handler on a non-local queue would have to use Arc<T>.

To ensure that these event handlers are not accessed or dropped on different threads, this advantage comes with the following restrictions:

• If a local queue was created on a thread X:
  • Event handlers must be attached on X.
  • The queue must only be dispatched on X.
  • The QueueOwner owning the queue must be dropped on X.
  • Proxies attached to the queue must only be destroyed on X.
    • Note: Proxies are destroyed when proxy::destroy is called or when a destructor request is sent or implicitly when the last reference to the proxy is dropped.

These restrictions are checked at runtime and will lead to panics if violated.

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();

// Create a local queue.
let queue = con.create_local_queue(c"queue name");
let display: WlDisplay = queue.display();

// Create an `Rc` and use it as an event handler.
let done = Rc::new(Cell::new(false));
let done2 = done.clone();
let sync = display.sync();
proxy::set_event_handler_local(&sync, WlCallback::on_done(move |_, _| done2.set(true)));

// Calling this function from another thread would panic.
queue.dispatch_roundtrip_blocking().unwrap();

assert!(done.get());

Locking

Each queue contains a re-entrant mutex. Re-entrant means that a thread that already holds the lock can acquire it again.

This lock can be acquired explicitly by calling Queue::lock_dispatch. You might want to use this function if you’re dispatching the queue from multiple threads to avoid lock inversion. For example, consider the following situation:

• Thread 1: Acquires the lock of some shared state.
• Thread 2: Starts dispatching and acquires the queue’s re-entrant lock.
• Thread 2: Calls an event handler which tries to lock the shared state and blocks.
• Thread 1: Destroys a proxy which will implicitly acquire the queue’s re-entrant lock. This deadlocks.

Instead, thread 1 could call Queue::lock_dispatch before locking the shared state to prevent the lock inversion.

This deadlock concern does not apply if the queue is only ever used from a single thread or if the queue is a local queue. If you need to poll the wayland socket on a separate thread, you can use BorrowedQueue::wait_for_events and send a message to the main thread when the future completes.

The lock is acquired implicitly in the following situations:

• The lock is held for the entirety of the following function calls:
  • Queue::dispatch_pending
• The lock is sometimes held during the following function calls but not while they are waiting for new events:
  • Queue::dispatch_blocking
  • Queue::dispatch_roundtrip_blocking
• The lock is sometimes held while the futures produced by the following functions are being polled but not while they are waiting for new events:
  • Queue::dispatch_async
  • Queue::dispatch_roundtrip_async
• The lock is held at the start and the end of the following function calls but not while invoking the callback:
  • Queue::dispatch_scope_blocking
• The lock is sometimes held while the futures produced by the following functions are being polled but not while polling the future passed as an argument:
  • Queue::dispatch_scope_async
• The lock is held while attaching an event handler to a proxy.
• The lock is held when a proxy with an event handler is being destroyed:
  • When sending a destructor request.
  • When calling proxy::destroy.
  • Implicitly when dropping the last reference to a proxy.
• The lock is held while dropping the QueueOwner of the queue.

Implementations

impl Queue

pub fn dispatch_scope_blocking<'env, T, F>(&self, f: F) -> T

where F: for<'scope> FnOnce(&'scope Scope<'scope, 'env>) -> T,

Creates a blocking scope for event handlers with shorter than 'static lifetime.

The scope can be used to attach event handlers to proxies. The following restriction applies: Such event handlers will only be invoked while inside this function. Once this function returns, the OwnedProxy::NO_OP_EVENT_HANDLER of the proxy is invoked instead.

Panic

Panics if this is a local queue and the current thread is not the thread that this queue was created in.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_local_queue(c"queue name");

let sync = queue.display::<WlDisplay>().sync();
let done = Cell::new(false);
queue.dispatch_scope_blocking(|scope| {
    scope.set_event_handler_local(&sync, WlCallback::on_done(|_, _| done.set(true)));
    queue.dispatch_roundtrip_blocking().unwrap();
});
assert!(done.get());

Examples found in repository

examples/poll-integration/../common/singletons.rs (lines 62-70)

pub fn get_singletons(display: &WlDisplay) -> Singletons {
    let map = Mutex::new(HashMap::new());

    let queue = proxy::queue(display);
    let wl_registry = display.get_registry();

    queue.dispatch_scope_blocking(|scope| {
        scope.set_event_handler(
            &wl_registry,
            WlRegistry::on_global(|_, name, interface, version| {
                map.lock().insert(interface.to_owned(), (name, version));
            }),
        );
        queue.dispatch_roundtrip_blocking().unwrap();
    });

    Singletons {
        wl_registry,
        map: map.into_inner(),
    }
}

examples/get-registry/main.rs (lines 35-50)

fn get_registry_snapshot(queue: &Queue) -> (WlRegistry, Vec<Global>) {
    // Create a new registry that will receive the globals and can later be used to
    // bind them.
    let registry = queue.display::<WlDisplay>().get_registry();
    let globals = Mutex::new(vec![]);
    // Since we don't care about registry events after this function returns, we can
    // use a dispatch scope. The event handlers in this scope will not be called after
    // the function returns.
    queue.dispatch_scope_blocking(|scope| {
        scope.set_event_handler(
            &registry,
            // Since we only want to create a snapshot, we don't care about
            // global_remove events. This allows us to use the functional event handler
            // form.
            WlRegistry::on_global(|_, name, interface, version| {
                globals.lock().push(Global {
                    name,
                    interface: interface.to_string(),
                    version,
                });
            }),
        );
        queue.dispatch_roundtrip_blocking().unwrap();
    });
    // The event handler will no longer be called after this function returns but
    // the registry can still be used to bind globals.
    (registry, globals.into_inner())
}

pub async fn dispatch_scope_async<'env, T, F>(&self, f: F) -> T

where F: for<'scope> AsyncFnOnce(&'scope Scope<'scope, 'env>) -> T,

Creates an async scope for event handlers with shorter than 'static lifetime.

The scope can be used to attach event handlers to proxies. The following restriction applies: Such event handlers will only be invoked while the future is being polled. If an event needs to be dispatched in any other situation, the OwnedProxy::NO_OP_EVENT_HANDLER of the proxy is invoked instead.

In particular, dispatching the queue from a outside this future while this future exists is unlikely to have the desired effect.

Panic

Panics if this is a local queue and the thread polling the future is not the thread that this queue was created in.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_local_queue(c"queue name");

let sync = queue.display::<WlDisplay>().sync();
let done = Cell::new(false);
queue.dispatch_scope_async(async |scope| {
    scope.set_event_handler_local(&sync, WlCallback::on_done(|_, _| done.set(true)));
    queue.dispatch_roundtrip_async().await.unwrap();
}).await;
assert!(done.get());

Examples found in repository

examples/poll-integration/../common/singletons.rs (lines 85-93)

pub async fn get_singletons_async(display: &WlDisplay) -> Singletons {
    let map = Mutex::new(HashMap::new());

    let queue = proxy::queue(display);
    let wl_registry = display.get_registry();

    queue
        .dispatch_scope_async(async |scope| {
            scope.set_event_handler(
                &wl_registry,
                WlRegistry::on_global(|_, name, interface, version| {
                    map.lock().insert(interface.to_owned(), (name, version));
                }),
            );
            queue.dispatch_roundtrip_async().await.unwrap();
        })
        .await;

    Singletons {
        wl_registry,
        map: map.into_inner(),
    }
}

examples/async-roundtrip/main.rs (lines 18-29)

async fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"async-roundtrip");
    let registry = queue.display::<WlDisplay>().get_registry();
    let num_globals = Cell::new(0);
    queue
        .dispatch_scope_async(async |scope| {
            scope.set_event_handler_local(
                &registry,
                WlRegistry::on_global(|_, _, _, _| {
                    num_globals.set(num_globals.get() + 1);
                }),
            );
            // This function can be used to perform an async roundtrip. It is
            // compatible with any async runtime. This example also demonstrates
            // that this works in combination with scoped event handlers.
            queue.dispatch_roundtrip_async().await.unwrap();
        })
        .await;
    println!("number of globals: {}", num_globals.get());
}

impl Queue

pub fn libwayland(&self) -> &'static Libwayland

Returns a reference to the Libwayland singleton.

Examples found in repository

examples/poll-integration/../common/protocols/wayland/wl_display.rs (line 363)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function required that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlDisplayRef>(slf) };
        match opcode {
            0 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an object
                let arg0 = unsafe {
                    if let Some(p) = NonNull::new(args[0].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                let arg0 = arg0.as_ref();
                // SAFETY: - INTERFACE requires that args[1] contains a uint
                let arg1 = unsafe { args[1].u };
                // SAFETY: - INTERFACE requires that args[2] contains a string
                //         - if the pointer is not null, then it is a c string
                let arg2 = unsafe { convert_string_arg("wl_display", "message", args[2].s) };
                self.0.error(slf, arg0, arg1, arg2);
            }
            1 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                self.0.delete_id(slf, arg0);
            }
            _ => {
                invalid_opcode("wl_display", opcode);
            }
        }
    }

examples/poll-integration/../common/protocols/wayland/wl_surface.rs (line 984)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function required that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(slf) };
        match opcode {
            0 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an object
                let arg0 = unsafe {
                    if let Some(p) = NonNull::new(args[0].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlOutput::WL_INTERFACE
                let arg0 = arg0.as_ref().map(|arg0| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlOutputRef>(arg0)
                });
                self.0.enter(slf, arg0);
            }
            1 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an object
                let arg0 = unsafe {
                    if let Some(p) = NonNull::new(args[0].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlOutput::WL_INTERFACE
                let arg0 = arg0.as_ref().map(|arg0| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlOutputRef>(arg0)
                });
                self.0.leave(slf, arg0);
            }
            2 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an int
                let arg0 = unsafe { args[0].i };
                self.0.preferred_buffer_scale(slf, arg0);
            }
            3 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { WlOutputTransform(args[0].u) };
                self.0.preferred_buffer_transform(slf, arg0);
            }
            _ => {
                invalid_opcode("wl_surface", opcode);
            }
        }
    }

examples/poll-integration/../common/protocols/wayland/wl_touch.rs (line 439)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function required that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlTouchRef>(slf) };
        match opcode {
            0 => {
                // SAFETY: INTERFACE requires that there are 6 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 6]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains a uint
                let arg1 = unsafe { args[1].u };
                // SAFETY: - INTERFACE requires that args[2] contains an object
                let arg2 = unsafe {
                    if let Some(p) = NonNull::new(args[2].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlSurface::WL_INTERFACE
                let arg2 = arg2.as_ref().map(|arg2| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(arg2)
                });
                // SAFETY: - INTERFACE requires that args[3] contains an int
                let arg3 = unsafe { args[3].i };
                // SAFETY: - INTERFACE requires that args[4] contains a fixed
                let arg4 = unsafe { Fixed::from_wire(args[4].f) };
                // SAFETY: - INTERFACE requires that args[5] contains a fixed
                let arg5 = unsafe { Fixed::from_wire(args[5].f) };
                self.0.down(slf, arg0, arg1, arg2, arg3, arg4, arg5);
            }
            1 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains a uint
                let arg1 = unsafe { args[1].u };
                // SAFETY: - INTERFACE requires that args[2] contains an int
                let arg2 = unsafe { args[2].i };
                self.0.up(slf, arg0, arg1, arg2);
            }
            2 => {
                // SAFETY: INTERFACE requires that there are 4 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 4]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains an int
                let arg1 = unsafe { args[1].i };
                // SAFETY: - INTERFACE requires that args[2] contains a fixed
                let arg2 = unsafe { Fixed::from_wire(args[2].f) };
                // SAFETY: - INTERFACE requires that args[3] contains a fixed
                let arg3 = unsafe { Fixed::from_wire(args[3].f) };
                self.0.motion(slf, arg0, arg1, arg2, arg3);
            }
            3 => {
                self.0.frame(slf);
            }
            4 => {
                self.0.cancel(slf);
            }
            5 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an int
                let arg0 = unsafe { args[0].i };
                // SAFETY: - INTERFACE requires that args[1] contains a fixed
                let arg1 = unsafe { Fixed::from_wire(args[1].f) };
                // SAFETY: - INTERFACE requires that args[2] contains a fixed
                let arg2 = unsafe { Fixed::from_wire(args[2].f) };
                self.0.shape(slf, arg0, arg1, arg2);
            }
            6 => {
                // SAFETY: INTERFACE requires that there are 2 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 2]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an int
                let arg0 = unsafe { args[0].i };
                // SAFETY: - INTERFACE requires that args[1] contains a fixed
                let arg1 = unsafe { Fixed::from_wire(args[1].f) };
                self.0.orientation(slf, arg0, arg1);
            }
            _ => {
                invalid_opcode("wl_touch", opcode);
            }
        }
    }

examples/poll-integration/../common/protocols/wayland/wl_data_device.rs (line 525)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function required that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlDataDeviceRef>(slf) };
        match opcode {
            0 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an object
                //         - ownership is transferred to this function
                //         - INTERFACE requires that the object has the interface WlDataOffer::WL_INTERFACE
                let arg0 = unsafe {
                    UntypedOwnedProxy::from_plain_wl_proxy(
                        queue,
                        NonNull::new_unchecked(args[0].o.cast()),
                        WlDataOffer::WL_INTERFACE,
                    )
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlDataOffer::WL_INTERFACE
                let arg0 = unsafe { proxy::low_level::from_untyped_owned::<WlDataOffer>(arg0) };
                self.0.data_offer(slf, arg0);
            }
            1 => {
                // SAFETY: INTERFACE requires that there are 5 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 5]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains an object
                let arg1 = unsafe {
                    if let Some(p) = NonNull::new(args[1].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlSurface::WL_INTERFACE
                let arg1 = arg1.as_ref().map(|arg1| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(arg1)
                });
                // SAFETY: - INTERFACE requires that args[2] contains a fixed
                let arg2 = unsafe { Fixed::from_wire(args[2].f) };
                // SAFETY: - INTERFACE requires that args[3] contains a fixed
                let arg3 = unsafe { Fixed::from_wire(args[3].f) };
                // SAFETY: - INTERFACE requires that args[4] contains an object
                let arg4 = unsafe {
                    if let Some(p) = NonNull::new(args[4].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlDataOffer::WL_INTERFACE
                let arg4 = arg4.as_ref().map(|arg4| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlDataOfferRef>(arg4)
                });
                self.0.enter(slf, arg0, arg1, arg2, arg3, arg4);
            }
            2 => {
                self.0.leave(slf);
            }
            3 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains a fixed
                let arg1 = unsafe { Fixed::from_wire(args[1].f) };
                // SAFETY: - INTERFACE requires that args[2] contains a fixed
                let arg2 = unsafe { Fixed::from_wire(args[2].f) };
                self.0.motion(slf, arg0, arg1, arg2);
            }
            4 => {
                self.0.drop(slf);
            }
            5 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an object
                let arg0 = unsafe {
                    if let Some(p) = NonNull::new(args[0].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlDataOffer::WL_INTERFACE
                let arg0 = arg0.as_ref().map(|arg0| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlDataOfferRef>(arg0)
                });
                self.0.selection(slf, arg0);
            }
            _ => {
                invalid_opcode("wl_data_device", opcode);
            }
        }
    }

examples/poll-integration/../common/protocols/wayland/wl_keyboard.rs (line 463)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function required that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlKeyboardRef>(slf) };
        match opcode {
            0 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { WlKeyboardKeymapFormat(args[0].u) };
                // SAFETY: - INTERFACE requires that args[1] contains a file descriptor
                let arg1 = unsafe { OwnedFd::from_raw_fd(args[1].h) };
                // SAFETY: - INTERFACE requires that args[2] contains a uint
                let arg2 = unsafe { args[2].u };
                self.0.keymap(slf, arg0, arg1, arg2);
            }
            1 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains an object
                let arg1 = unsafe {
                    if let Some(p) = NonNull::new(args[1].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlSurface::WL_INTERFACE
                let arg1 = arg1.as_ref().map(|arg1| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(arg1)
                });
                // SAFETY: - INTERFACE requires that args[2] contains an array
                let arg2 = unsafe {
                    let a = &*args[2].a;
                    std::slice::from_raw_parts(a.data.cast(), a.size)
                };
                self.0.enter(slf, arg0, arg1, arg2);
            }
            2 => {
                // SAFETY: INTERFACE requires that there are 2 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 2]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains an object
                let arg1 = unsafe {
                    if let Some(p) = NonNull::new(args[1].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlSurface::WL_INTERFACE
                let arg1 = arg1.as_ref().map(|arg1| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(arg1)
                });
                self.0.leave(slf, arg0, arg1);
            }
            3 => {
                // SAFETY: INTERFACE requires that there are 4 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 4]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains a uint
                let arg1 = unsafe { args[1].u };
                // SAFETY: - INTERFACE requires that args[2] contains a uint
                let arg2 = unsafe { args[2].u };
                // SAFETY: - INTERFACE requires that args[3] contains a uint
                let arg3 = unsafe { WlKeyboardKeyState(args[3].u) };
                self.0.key(slf, arg0, arg1, arg2, arg3);
            }
            4 => {
                // SAFETY: INTERFACE requires that there are 5 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 5]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains a uint
                let arg1 = unsafe { args[1].u };
                // SAFETY: - INTERFACE requires that args[2] contains a uint
                let arg2 = unsafe { args[2].u };
                // SAFETY: - INTERFACE requires that args[3] contains a uint
                let arg3 = unsafe { args[3].u };
                // SAFETY: - INTERFACE requires that args[4] contains a uint
                let arg4 = unsafe { args[4].u };
                self.0.modifiers(slf, arg0, arg1, arg2, arg3, arg4);
            }
            5 => {
                // SAFETY: INTERFACE requires that there are 2 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 2]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an int
                let arg0 = unsafe { args[0].i };
                // SAFETY: - INTERFACE requires that args[1] contains an int
                let arg1 = unsafe { args[1].i };
                self.0.repeat_info(slf, arg0, arg1);
            }
            _ => {
                invalid_opcode("wl_keyboard", opcode);
            }
        }
    }

examples/poll-integration/../common/protocols/tablet_v2/zwp_tablet_pad_v2.rs (line 548)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function required that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<ZwpTabletPadV2Ref>(slf) };
        match opcode {
            0 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains an object
                //         - ownership is transferred to this function
                //         - INTERFACE requires that the object has the interface ZwpTabletPadGroupV2::WL_INTERFACE
                let arg0 = unsafe {
                    UntypedOwnedProxy::from_plain_wl_proxy(
                        queue,
                        NonNull::new_unchecked(args[0].o.cast()),
                        ZwpTabletPadGroupV2::WL_INTERFACE,
                    )
                };
                // SAFETY: - INTERFACE requires that the object has the interface ZwpTabletPadGroupV2::WL_INTERFACE
                let arg0 =
                    unsafe { proxy::low_level::from_untyped_owned::<ZwpTabletPadGroupV2>(arg0) };
                self.0.group(slf, arg0);
            }
            1 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a string
                //         - if the pointer is not null, then it is a c string
                let arg0 = unsafe { convert_string_arg("zwp_tablet_pad_v2", "path", args[0].s) };
                self.0.path(slf, arg0);
            }
            2 => {
                // SAFETY: INTERFACE requires that there are 1 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 1]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                self.0.buttons(slf, arg0);
            }
            3 => {
                self.0.done(slf);
            }
            4 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains a uint
                let arg1 = unsafe { args[1].u };
                // SAFETY: - INTERFACE requires that args[2] contains a uint
                let arg2 = unsafe { ZwpTabletPadV2ButtonState(args[2].u) };
                self.0.button(slf, arg0, arg1, arg2);
            }
            5 => {
                // SAFETY: INTERFACE requires that there are 3 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 3]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains an object
                let arg1 = unsafe {
                    if let Some(p) = NonNull::new(args[1].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface ZwpTabletV2::WL_INTERFACE
                let arg1 = arg1.as_ref().map(|arg1| unsafe {
                    proxy::low_level::from_untyped_borrowed::<ZwpTabletV2Ref>(arg1)
                });
                // SAFETY: - INTERFACE requires that args[2] contains an object
                let arg2 = unsafe {
                    if let Some(p) = NonNull::new(args[2].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlSurface::WL_INTERFACE
                let arg2 = arg2.as_ref().map(|arg2| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(arg2)
                });
                self.0.enter(slf, arg0, arg1, arg2);
            }
            6 => {
                // SAFETY: INTERFACE requires that there are 2 arguments
                let args = unsafe { &*args.cast::<[wl_argument; 2]>() };
                // SAFETY: - INTERFACE requires that args[0] contains a uint
                let arg0 = unsafe { args[0].u };
                // SAFETY: - INTERFACE requires that args[1] contains an object
                let arg1 = unsafe {
                    if let Some(p) = NonNull::new(args[1].o.cast()) {
                        Some(UntypedBorrowedProxy::new_immutable(queue.libwayland(), p))
                    } else {
                        None
                    }
                };
                // SAFETY: - INTERFACE requires that the object has the interface WlSurface::WL_INTERFACE
                let arg1 = arg1.as_ref().map(|arg1| unsafe {
                    proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(arg1)
                });
                self.0.leave(slf, arg0, arg1);
            }
            7 => {
                self.0.removed(slf);
            }
            _ => {
                invalid_opcode("zwp_tablet_pad_v2", opcode);
            }
        }
    }

Additional examples can be found in:

• examples/poll-integration/../common/protocols/wayland/wl_pointer.rs
• examples/poll-integration/../common/protocols/tablet_v2/zwp_tablet_tool_v2.rs

pub fn connection(&self) -> &Connection

Returns the connection that this queue belongs to.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");
assert_eq!(queue.connection(), &con);

pub fn lock_dispatch(&self) -> DispatchLock<'_>

Acquires the queue’s re-entrant lock.

See the description of Queue for why you might use this.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");

let lock = queue.lock_dispatch();

let thread = {
    let queue = queue.clone();
    thread::spawn(move || {
        // this dispatch will not start until the lock is dropped.
        queue.dispatch_roundtrip_blocking().unwrap();
    })
};

// this dispatch starts immediately since the lock is re-entrant
queue.dispatch_roundtrip_blocking().unwrap();

drop(lock);
thread.join().unwrap();

pub fn display<T>(&self) -> T

where T: OwnedProxy,

Creates a wrapper proxy around the singleton wl_display object.

The proxy is a wrapper and no event handler can be attached to it.

The proxy is attached to this queue.

Panic

Panics if the interface of T is not compatible with the wl_display interface.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");
let display: WlDisplay = queue.display();
assert_eq!(proxy::queue(&display), &*queue);
assert_eq!(proxy::id(&*display), 1);

Examples found in repository

examples/async-wait/main.rs (line 24)

fn create_sync(queue: &Queue, n: u64) {
    let sync = queue.display::<WlDisplay>().sync();
    proxy::set_event_handler(
        &sync.clone(),
        WlCallback::on_done(move |_, _| {
            println!("done! ({n})");
            proxy::destroy(&sync);
            create_sync(proxy::queue(&sync), n + 1);
        }),
    );
}

examples/poll-integration/main.rs (line 49)

fn create_sync(queue: &Queue, n: u64) {
    let sync = queue.display::<WlDisplay>().sync();
    proxy::set_event_handler(
        &sync.clone(),
        WlCallback::on_done(move |_, _| {
            println!("done! ({n})");
            proxy::destroy(&sync);
            create_sync(proxy::queue(&sync), n + 1);
        }),
    );
}

examples/simple-window/main.rs (line 10)

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"simple-window");
    let singletons = get_singletons(&queue.display());
    let simple_window = simple_window::prepare(singletons);
    while !simple_window.exit.get() {
        queue.dispatch_blocking().unwrap();
    }
}

examples/async-window/main.rs (line 13)

async fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"async-window");
    let singletons = get_singletons_async(&queue.display()).await;
    let simple_window = simple_window::prepare(singletons);
    while !simple_window.exit.get() {
        queue.dispatch_async().await.unwrap();
    }
}

examples/keyboard-events/main.rs (line 30)

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"keyboard-events");
    let singletons = get_singletons(&queue.display());
    let simple_window = simple_window::prepare(singletons);

    let wl_registry = queue.display::<WlDisplay>().get_registry();
    proxy::set_event_handler_local(
        &wl_registry,
        RegistryEventHandler {
            wl_registry: wl_registry.clone(),
            seats: Default::default(),
        },
    );

    while !simple_window.exit.get() {
        queue.dispatch_blocking().unwrap();
    }
}

examples/async-roundtrip/main.rs (line 15)

async fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"async-roundtrip");
    let registry = queue.display::<WlDisplay>().get_registry();
    let num_globals = Cell::new(0);
    queue
        .dispatch_scope_async(async |scope| {
            scope.set_event_handler_local(
                &registry,
                WlRegistry::on_global(|_, _, _, _| {
                    num_globals.set(num_globals.get() + 1);
                }),
            );
            // This function can be used to perform an async roundtrip. It is
            // compatible with any async runtime. This example also demonstrates
            // that this works in combination with scoped event handlers.
            queue.dispatch_roundtrip_async().await.unwrap();
        })
        .await;
    println!("number of globals: {}", num_globals.get());
}

Additional examples can be found in:

• examples/get-registry/main.rs
• examples/hello-wayland/main.rs
• examples/poll-integration/../common/simple_window.rs

pub fn is_local(&self) -> bool

Returns whether this is a local queue.

The documentation of the Queue type explains the difference between local and non-local queues.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue1 = con.create_queue(c"non-local queue");
let queue2 = con.create_local_queue(c"local queue");

assert!(queue1.is_non_local());
assert!(queue2.is_local());

pub fn is_non_local(&self) -> bool

Returns whether this is not a local queue.

This is the same as !self.is_local().

The documentation of the Queue type explains the difference between local and non-local queues.

pub fn wl_event_queue(&self) -> NonNull<wl_event_queue>

Returns the wl_event_queue pointer of this queue.

The returned pointer is valid for as long as this queue exists.

You must not dispatch the queue except through the Queue interface. Otherwise the behavior is undefined.

pub fn dispatch_blocking(&self) -> Result<u64>

Blocks the current thread until at least one event has been dispatched.

If you are in an async context, then you might want to use Queue::dispatch_async instead.

This function should not be used when integrating with an existing, poll-based event loop, as it might block indefinitely. Use Connection::create_watcher and Queue::dispatch_pending instead.

The returned number is the number of events that have been dispatched by this call. The number can be zero if another thread dispatched the events before us.

Panic

Panics if this is a local queue and the current thread is not the thread that this queue was created in.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");

// For this example, ensure that the compositor sends an event in the near future.
let _sync = queue.display::<WlDisplay>().sync();

queue.dispatch_blocking().unwrap();

Examples found in repository

examples/simple-window/main.rs (line 13)

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"simple-window");
    let singletons = get_singletons(&queue.display());
    let simple_window = simple_window::prepare(singletons);
    while !simple_window.exit.get() {
        queue.dispatch_blocking().unwrap();
    }
}

examples/keyboard-events/main.rs (line 43)

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"keyboard-events");
    let singletons = get_singletons(&queue.display());
    let simple_window = simple_window::prepare(singletons);

    let wl_registry = queue.display::<WlDisplay>().get_registry();
    proxy::set_event_handler_local(
        &wl_registry,
        RegistryEventHandler {
            wl_registry: wl_registry.clone(),
            seats: Default::default(),
        },
    );

    while !simple_window.exit.get() {
        queue.dispatch_blocking().unwrap();
    }
}

pub async fn dispatch_async(&self) -> Result<u64>

Completes when at least one event has been dispatched.

This function is the same as Queue::dispatch_blocking except that it is async and does not block the current thread.

Panic

Panics if this is a local queue and the thread polling the future is not the thread that this queue was created in.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");

// For this example, ensure that the compositor sends an event in the near future.
let _sync = queue.display::<WlDisplay>().sync();

queue.dispatch_async().await.unwrap();

Examples found in repository

examples/async-window/main.rs (line 16)

async fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"async-window");
    let singletons = get_singletons_async(&queue.display()).await;
    let simple_window = simple_window::prepare(singletons);
    while !simple_window.exit.get() {
        queue.dispatch_async().await.unwrap();
    }
}

pub fn dispatch_pending(&self) -> Result<u64>

Dispatches enqueued events.

This function does not read new events from the file descriptor.

This function can be used together with BorrowedQueue::wait_for_events or Queue::create_watcher to dispatch the queue in an async context or event loop respectively.

The returned number is the number of events that were dispatched.

Panic

Panics if this is a local queue and the current thread is not the thread that this queue was created in.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");
let display: WlDisplay = queue.display();

let done = Arc::new(AtomicBool::new(false));
let done2 = done.clone();
let sync = display.sync();
proxy::set_event_handler(&sync, WlCallback::on_done(move |_, _| {
    done2.store(true, Relaxed);
}));

while !done.load(Relaxed) {
    queue.wait_for_events().await.unwrap();
    // Dispatch the events.
    queue.dispatch_pending().unwrap();
}

Examples found in repository

examples/async-wait/main.rs (line 19)

async fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"async-wait");

    create_sync(&queue, 1);

    loop {
        queue.wait_for_events().await.unwrap();
        queue.dispatch_pending().unwrap();
    }
}

examples/poll-integration/main.rs (line 39)

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"poll-integration");

    // The watcher exposes a file descriptor that will become readable when the queue
    // has new events.
    let watcher = queue.create_watcher().unwrap();
    let token = Token(0);

    create_sync(&queue, 1);

    let mut events = mio::Events::with_capacity(2);
    let mut poll = mio::Poll::new().unwrap();
    poll.registry()
        .register(
            &mut SourceFd(&watcher.as_raw_fd()),
            token,
            Interest::READABLE,
        )
        .unwrap();

    loop {
        // Flush requests before polling.
        con.flush().unwrap();
        poll.poll(&mut events, None).unwrap();
        for event in events.iter() {
            if event.token() == token {
                queue.dispatch_pending().unwrap();
                // Reset the watcher to clear the readability status.
                watcher.reset().unwrap();
            }
        }
        events.clear();
    }
}

pub fn dispatch_roundtrip_blocking(&self) -> Result<()>

Blocks the current thread until the compositor has processed all previous requests and all of its response events have been dispatched.

If you are in an async context, then you might want to use Queue::dispatch_roundtrip_async instead.

Since this function usually returns quickly, you might use this function even when integrating a wayland connection into an existing event loop and even in an async context. For example, a library that creates buffers might use this function during initialization to receive the full list of supported formats before returning.

If this function returns Ok(()), then the function returns after (in the sense of the C++ memory model) the event handlers of all previous events have been invoked.

Panic

Panics if this is a local queue and the current thread is not the thread that this queue was created in.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"");
let display: WlDisplay = queue.display();

// send some messages to the compositor
let done = Arc::new(AtomicBool::new(false));
let done2 = done.clone();
let sync = display.sync();
proxy::set_event_handler(&sync, WlCallback::on_done(move |_, _| {
    done2.store(true, Relaxed);
}));

// perform a roundtrip
queue.dispatch_roundtrip_blocking().unwrap();

// assert that we've received the response
assert!(done.load(Relaxed));

Examples found in repository

examples/poll-integration/../common/singletons.rs (line 69)

pub fn get_singletons(display: &WlDisplay) -> Singletons {
    let map = Mutex::new(HashMap::new());

    let queue = proxy::queue(display);
    let wl_registry = display.get_registry();

    queue.dispatch_scope_blocking(|scope| {
        scope.set_event_handler(
            &wl_registry,
            WlRegistry::on_global(|_, name, interface, version| {
                map.lock().insert(interface.to_owned(), (name, version));
            }),
        );
        queue.dispatch_roundtrip_blocking().unwrap();
    });

    Singletons {
        wl_registry,
        map: map.into_inner(),
    }
}

examples/get-registry/main.rs (line 49)

fn get_registry_snapshot(queue: &Queue) -> (WlRegistry, Vec<Global>) {
    // Create a new registry that will receive the globals and can later be used to
    // bind them.
    let registry = queue.display::<WlDisplay>().get_registry();
    let globals = Mutex::new(vec![]);
    // Since we don't care about registry events after this function returns, we can
    // use a dispatch scope. The event handlers in this scope will not be called after
    // the function returns.
    queue.dispatch_scope_blocking(|scope| {
        scope.set_event_handler(
            &registry,
            // Since we only want to create a snapshot, we don't care about
            // global_remove events. This allows us to use the functional event handler
            // form.
            WlRegistry::on_global(|_, name, interface, version| {
                globals.lock().push(Global {
                    name,
                    interface: interface.to_string(),
                    version,
                });
            }),
        );
        queue.dispatch_roundtrip_blocking().unwrap();
    });
    // The event handler will no longer be called after this function returns but
    // the registry can still be used to bind globals.
    (registry, globals.into_inner())
}

examples/hello-wayland/main.rs (line 32)

fn main() {
    // Load the `libwayland-client.so` dynamic library.
    let lib = Libwayland::open().unwrap();
    // Connect to the default display determined by the `WAYLAND_DISPLAY` env var.
    let con = lib.connect_to_default_display().unwrap();
    // Create a new event queue with the name `hello-wayland`. This name will show up
    // when debugging applications with `WAYLAND_DEBUG=1`.
    let queue = con.create_queue(c"hello-wayland");
    // Get a reference to the `wl_display` singleton. This type was generated with the
    // `wl-client-builder` crate.
    let display: WlDisplay = queue.display();
    // Create a `wl_callback` object. The compositor will immediately respond with a
    // `wl_callback.done` event.
    let sync = display.sync();
    // Set the event handler of the proxy.
    proxy::set_event_handler(
        &sync,
        // When only handling a single event, the following functional form can be used.
        // In general, and when handling more than one event, the event handler trait must
        // be implemented. In this case, `WlCallbackEventHandler`.
        WlCallback::on_done(|_, _| println!("Hello wayland!")),
    );
    // Perform a roundtrip to ensure that the `done` event has been dispatched.
    queue.dispatch_roundtrip_blocking().unwrap();
}

pub async fn dispatch_roundtrip_async(&self) -> Result<()>

Completes when the compositor has processed all previous requests and all of its response events have been dispatched.

This function is the same as Queue::dispatch_roundtrip_blocking except that it is async and does not block the current thread.

If the future completes with Ok(()), then the future completes after (in the sense of the C++ memory model) the event handlers of all previous events have been invoked.

Panic

Panics if this is a local queue and the thread polling the future is not the thread that this queue was created in.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");
let display: WlDisplay = queue.display();

// send some messages to the compositor
let done = Arc::new(AtomicBool::new(false));
let done2 = done.clone();
let sync = display.sync();
proxy::set_event_handler(&sync, WlCallback::on_done(move |_, _| {
    done2.store(true, Relaxed);
}));

// perform a roundtrip
queue.dispatch_roundtrip_async().await.unwrap();

// assert that we've received the response
assert!(done.load(Relaxed));

Examples found in repository

examples/poll-integration/../common/singletons.rs (line 92)

pub async fn get_singletons_async(display: &WlDisplay) -> Singletons {
    let map = Mutex::new(HashMap::new());

    let queue = proxy::queue(display);
    let wl_registry = display.get_registry();

    queue
        .dispatch_scope_async(async |scope| {
            scope.set_event_handler(
                &wl_registry,
                WlRegistry::on_global(|_, name, interface, version| {
                    map.lock().insert(interface.to_owned(), (name, version));
                }),
            );
            queue.dispatch_roundtrip_async().await.unwrap();
        })
        .await;

    Singletons {
        wl_registry,
        map: map.into_inner(),
    }
}

examples/async-roundtrip/main.rs (line 28)

async fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"async-roundtrip");
    let registry = queue.display::<WlDisplay>().get_registry();
    let num_globals = Cell::new(0);
    queue
        .dispatch_scope_async(async |scope| {
            scope.set_event_handler_local(
                &registry,
                WlRegistry::on_global(|_, _, _, _| {
                    num_globals.set(num_globals.get() + 1);
                }),
            );
            // This function can be used to perform an async roundtrip. It is
            // compatible with any async runtime. This example also demonstrates
            // that this works in combination with scoped event handlers.
            queue.dispatch_roundtrip_async().await.unwrap();
        })
        .await;
    println!("number of globals: {}", num_globals.get());
}

pub fn wrap_proxy<P>(&self, proxy: &P) -> P::Owned

where P: BorrowedProxy,

Creates a wrapper for an existing proxy.

The wrapper will be assigned to this queue. No event handler can be assigned to the wrapper.

Panic

• Panics if the proxy and this queue don’t belong to the same wl_display.
• Panics if the proxy is already destroyed.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();

let queue1 = con.create_queue(c"queue name");
let display1: WlDisplay = queue1.display();
assert_eq!(proxy::queue(&display1), &*queue1);

let queue2 = con.create_queue(c"second queue");
let display2 = queue2.wrap_proxy(&*display1);
assert_eq!(proxy::queue(&display2), &*queue2);

pub unsafe fn wrap_wl_proxy<P>(&self, proxy: NonNull<wl_proxy>) -> P

where P: OwnedProxy,

Creates a wrapper for an existing wl_proxy.

The wrapper will be assigned to this queue. No event handler can be assigned to the wrapper.

If the wl_proxy already has a safe wrapper, the Queue::wrap_proxy function can be used instead.

Panic

• Panics if the proxy and this queue don’t belong to the same wl_display.

Safety

• proxy must be a valid pointer.
• proxy must have an interface compatible with P::WL_INTERFACE.

Example

Some frameworks, e.g. winit, expose libwayland wl_display and wl_surface pointers. These can be imported into this crate as follows:

unsafe fn wrap_foreign_surface(display: NonNull<c_void>, wl_surface: NonNull<c_void>) {
    let lib = Libwayland::open().unwrap();
    // SAFETY: ...
    let con = unsafe { lib.wrap_borrowed_pointer(display.cast()).unwrap() };
    let queue = con.create_queue(c"queue name");
    // SAFETY: ...
    let surface: WlSurface = unsafe { queue.wrap_wl_proxy(wl_surface.cast()) };
}

pub fn create_watcher(&self) -> Result<QueueWatcher>

Creates a QueueWatcher for event-loop integration.

This is a shorthand for calling Connection::create_watcher with a queue list containing exactly this queue.

Examples found in repository

examples/poll-integration/main.rs (line 18)

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"poll-integration");

    // The watcher exposes a file descriptor that will become readable when the queue
    // has new events.
    let watcher = queue.create_watcher().unwrap();
    let token = Token(0);

    create_sync(&queue, 1);

    let mut events = mio::Events::with_capacity(2);
    let mut poll = mio::Poll::new().unwrap();
    poll.registry()
        .register(
            &mut SourceFd(&watcher.as_raw_fd()),
            token,
            Interest::READABLE,
        )
        .unwrap();

    loop {
        // Flush requests before polling.
        con.flush().unwrap();
        poll.poll(&mut events, None).unwrap();
        for event in events.iter() {
            if event.token() == token {
                queue.dispatch_pending().unwrap();
                // Reset the watcher to clear the readability status.
                watcher.reset().unwrap();
            }
        }
        events.clear();
    }
}

Methods from Deref<Target = BorrowedQueue>

pub async fn wait_for_events(&self) -> Result<()>

Completes when there are new events in this queue.

When this function returns Ok(()), this queue has an event queued.

This is a shorthand for calling Connection::wait_for_events with a queue list consisting of exactly this queue.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");
let display: WlDisplay = queue.display();

let done = Arc::new(AtomicBool::new(false));
let done2 = done.clone();
let sync = display.sync();
proxy::set_event_handler(&sync, WlCallback::on_done(move |_, _| {
    done2.store(true, Release);
}));

while !done.load(Acquire) {
    queue.wait_for_events().await.unwrap();
    queue.dispatch_pending().unwrap();
}

Examples found in repository

examples/async-wait/main.rs (line 18)

async fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let queue = con.create_local_queue(c"async-wait");

    create_sync(&queue, 1);

    loop {
        queue.wait_for_events().await.unwrap();
        queue.dispatch_pending().unwrap();
    }
}

pub fn wl_event_queue(&self) -> Option<NonNull<wl_event_queue>>

Returns the wl_event_queue representing this queue.

This function returns None if and only if this queue is the default queue of the connection.

The returned pointer, if any, remains valid as long as this object exists.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");
let default_queue = con.borrow_default_queue();

assert_eq!((**queue).wl_event_queue(), Some(queue.wl_event_queue()));
assert_eq!(default_queue.wl_event_queue(), None);

Trait Implementations

impl Clone for Queue

fn clone(&self) -> Queue

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Queue

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

Formats the value using the given formatter.

impl Deref for Queue

type Target = BorrowedQueue

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl PartialEq for Queue

fn eq(&self, other: &Queue) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Queue