Struct Scope 

pub struct Scope<'scope, 'env: 'scope> { /* private fields */ }

A scope for event handlers with shorter than 'static lifetime.

Scopes are created by calling Queue::dispatch_scope_blocking and Queue::dispatch_scope_async.

Event handlers attached via a scope have the following, additional restriction: they will be dropped and therefore not be invoked after the lifetime of the scope has ended. The proxies can still be used to send requests or as arguments, but no event callbacks will be invoked. Instead, the OwnedProxy::NO_OP_EVENT_HANDLER will be invoked to prevent any memory leaks.

Async scopes created via Queue::dispatch_scope_async have one more restriction: event handlers will only be invoked while the returned future is being polled. Until the future completes, the queue should therefore only be dispatched from inside the future.

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());

Implementations

impl<'scope> Scope<'scope, '_>

pub fn set_event_handler<P, H>(&'scope self, proxy: &P, handler: H)

where P: OwnedProxy, P::Api: CreateEventHandler<H>, <P::Api as CreateEventHandler<H>>::EventHandler: Send + 'scope,

Sets the event handler of the proxy.

This function is the same as proxy::set_event_handler except that the event handler does not have to implement 'static and that the event handler will not be invoked after 'scope.

The proxy must belong to the queue that was used to create this scope.

Panic

This function panics whenever proxy::set_event_handler panics and also if the proxy does not belong to the queue that was used to create this scope.

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 sync = display.sync();
let done = AtomicBool::new(false);

queue.dispatch_scope_blocking(|scope| {
    // Attach the event handler.
    scope.set_event_handler(&sync, WlCallback::on_done(|_, _| done.store(true, Relaxed)));

    // Wait for the compositor to send the `done` message.
    queue.dispatch_roundtrip_blocking().unwrap();
});

// The event handler sets the value to `true`.
assert!(done.load(Relaxed));

Examples found in repository

examples/async-roundtrip/../common/singletons.rs (lines 63-68)

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(),
    }
}

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/get-registry/main.rs (lines 36-48)

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 fn set_event_handler_local<P, H>(&'scope self, proxy: &P, handler: H)

where P: OwnedProxy, P::Api: CreateEventHandler<H>, <P::Api as CreateEventHandler<H>>::EventHandler: 'scope,

Sets the !Send event handler of the proxy.

This function is the same as proxy::set_event_handler_local except that the event handler does not have to implement 'static and that the event handler will not be invoked after 'scope.

The proxy must belong to the queue that was used to create this scope.

Panic

This function panics whenever proxy::set_event_handler_local panics and also if the proxy does not belong to the queue that was used to create this scope.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_local_queue(c"queue name");
let display: WlDisplay = queue.display();
let sync = display.sync();
let done = Cell::new(false);

queue.dispatch_scope_blocking(|scope| {
    // Attach the event handler.
    scope.set_event_handler_local(&sync, WlCallback::on_done(|_, _| done.set(true)));

    // Wait for the compositor to send the `done` message.
    queue.dispatch_roundtrip_blocking().unwrap();
});

// The event handler sets the value to `true`.
assert!(done.get());

Examples found in repository

examples/async-roundtrip/main.rs (lines 19-24)

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());
}