Struct QueueOwner 

pub struct QueueOwner { /* private fields */ }

The owner of an event queue.

This is a thin wrapper around Queue and implements Deref<Target = Queue>.

The purpose of this type is to manage the lifetimes of proxies attached to queues. This is described in more detail in the documentation of Queue.

Methods from Deref<Target = 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/async-window/../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/async-window/../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());
}

pub fn with_data<T>(&self) -> QueueWithData<T>

where T: 'static,

Creates an adapter for queues with mutable data.

If the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data, then this function can only be used with the same T that was used in those function calls.

For convenience, if this queue was created without data, this function can be used with any T.

Panic

This function panics if this queue

• was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data, and
• it was created with a different data type.

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

Returns a reference to the Libwayland singleton.

Examples found in repository

examples/async-window/../common/protocols/wayland/wl_display.rs (line 364)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        data: *mut u8,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function requires 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/async-window/../common/protocols_data/wayland/wl_display.rs (line 381)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        data: *mut u8,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function requires that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlDisplayRef>(slf) };
        // SAFETY: This function requires that data is `&mut T` where `T`
        //         has the type id returned by `Self::mutable_type`, i.e.,
        //         `T = H::Data`.
        let data: &mut H::Data = unsafe { &mut *data.cast() };
        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(data, 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(data, slf, arg0);
            }
            _ => {
                invalid_opcode("wl_display", opcode);
            }
        }
    }

examples/async-window/../common/protocols/wayland/wl_surface.rs (line 985)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        data: *mut u8,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function requires 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/async-window/../common/protocols_data/wayland/wl_surface.rs (line 1006)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        data: *mut u8,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function requires that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlSurfaceRef>(slf) };
        // SAFETY: This function requires that data is `&mut T` where `T`
        //         has the type id returned by `Self::mutable_type`, i.e.,
        //         `T = H::Data`.
        let data: &mut H::Data = unsafe { &mut *data.cast() };
        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(data, 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(data, 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(data, 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(data, slf, arg0);
            }
            _ => {
                invalid_opcode("wl_surface", opcode);
            }
        }
    }

examples/async-window/../common/protocols/wayland/wl_touch.rs (line 440)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        data: *mut u8,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function requires 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/async-window/../common/protocols_data/wayland/wl_touch.rs (line 472)

    unsafe fn handle_event(
        &self,
        queue: &Queue,
        data: *mut u8,
        slf: &UntypedBorrowedProxy,
        opcode: u32,
        args: *mut wl_argument,
    ) {
        // SAFETY: This function requires that slf has the interface INTERFACE
        let slf = unsafe { proxy::low_level::from_untyped_borrowed::<WlTouchRef>(slf) };
        // SAFETY: This function requires that data is `&mut T` where `T`
        //         has the type id returned by `Self::mutable_type`, i.e.,
        //         `T = H::Data`.
        let data: &mut H::Data = unsafe { &mut *data.cast() };
        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(data, 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(data, 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(data, slf, arg0, arg1, arg2, arg3);
            }
            3 => {
                self.0.frame(data, slf);
            }
            4 => {
                self.0.cancel(data, 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(data, 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(data, slf, arg0, arg1);
            }
            _ => {
                invalid_opcode("wl_touch", opcode);
            }
        }
    }

Additional examples can be found in:

• examples/async-window/../common/protocols/wayland/wl_data_device.rs
• examples/async-window/../common/protocols_data/wayland/wl_data_device.rs
• examples/async-window/../common/protocols/wayland/wl_keyboard.rs
• examples/async-window/../common/protocols/tablet_v2/zwp_tablet_pad_v2.rs
• examples/async-window/../common/protocols_data/wayland/wl_keyboard.rs
• examples/async-window/../common/protocols_data/tablet_v2/zwp_tablet_pad_v2.rs
• examples/async-window/../common/protocols/wayland/wl_pointer.rs
• examples/async-window/../common/protocols_data/wayland/wl_pointer.rs
• examples/async-window/../common/protocols/tablet_v2/zwp_tablet_tool_v2.rs
• examples/async-window/../common/protocols_data/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-with-data/main.rs
• examples/get-registry/main.rs
• examples/hello-wayland/main.rs
• examples/async-window/../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.

This function cannot be used if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data. Use QueueWithData::dispatch_blocking 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.
• Panics if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data.

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.
• Panics if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data.

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.

This function cannot be used if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data. Use QueueWithData::dispatch_pending instead.

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.
• Panics if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data.

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.

This function cannot be used if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data. Use QueueWithData::dispatch_roundtrip_blocking instead.

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.
• Panics if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data.

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/async-window/../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.
• Panics if the queue was created with Connection::create_queue_with_data or Connection::create_local_queue_with_data.

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/async-window/../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 Debug for QueueOwner

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

Formats the value using the given formatter.

impl Deref for QueueOwner

type Target = Queue

The resulting type after dereferencing.

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

Dereferences the value.

impl Drop for QueueOwner

fn drop(&mut self)

Executes the destructor for this type.