Struct Connection 

pub struct Connection { /* private fields */ }

A connection to a wayland compositor.

You can create a connection by using one of the methods on Libwayland.

Each connection wraps a libwayland wl_display pointer. This pointer can be owned or borrowed. If the pointer is owned by the time the last reference to the connection is dropped, the wl_display is destroyed. If the connection owns the pointer, you can take ownership of the pointer by calling Connection::take_ownership.

Example

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

Implementations

impl Connection

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

Schedules outgoing messages to be sent to the compositor.

This function must be used if the application uses a QueueWatcher to integrate the connection into an event loop. The blocking or async integration methods perform a flush automatically.

This function never blocks. It only schedules messages to be flushed on another thread.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let queue = con.create_queue(c"queue name");
let watcher = queue.create_watcher().unwrap();
let token = mio::Token(0);
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();

// perform requests
// ...

// flush the requests
con.flush().unwrap();

// wait for new events
poll.poll(&mut events, None).unwrap();

Examples found in repository

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

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

impl Connection

pub async fn wait_for_events(&self, queues: &[&BorrowedQueue]) -> Result<()>

Waits for events on any number of event queues.

When this function returns Ok(()), at least one of the event queues has an event queued.

If no other thread is dispatching these queues, then this function will return Ok(()) as soon as this happens.

If the list of queues is empty, this function waits indefinitely.

This function flushes all requests made before this function call.

Panic

This function panics if the queues do not all belong to this connection.

pub fn create_watcher( &self, owned: &[&Queue], borrowed: impl IntoIterator<Item = BorrowedQueue>, ) -> Result<QueueWatcher>

Creates a QueueWatcher for event-loop integration.

See the documentation of QueueWatcher for details on when and how an application would use this.

Panic

This function panics if the queues do not all belong to this connection.

impl Connection

pub fn is_owned(&self) -> bool

Returns whether this connection owns the underlying wl_display.

When the last reference to the connection is dropped, the wl_display will be destroyed if and only if the display is owned at that time.

If this function returns false, then it will always return false.

If this function returns true, then it might return false in the future if ownership is consumed by calling Self::take_ownership.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
assert!(con.is_owned());
let wl_display = con.wl_display();
{
    // SAFETY: - We took the display from a freshly created Connection so it is valid.
    //         - We drop the connection before dropping the outer connection that
    //           owns the wl_display.
    let con = unsafe { lib.wrap_borrowed_pointer(wl_display).unwrap() };
    assert!(con.is_borrowed());
}

pub fn is_borrowed(&self) -> bool

Returns whether this connection borrows the underlying wl_display.

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

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

Returns the underlying wl_display pointer.

This is always a valid pointer.

Example

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

pub fn take_ownership(&self) -> Option<NonNull<wl_display>>

Takes ownership of the underlying wl_display.

If this returns Some, then ownership has been transferred from the connection to the caller. After this function returns, the connection no longer has ownership of the underlying wl_display and will not destroy the display.

Example

let lib = Libwayland::open().unwrap();
let wl_display = {
    let con = lib.connect_to_default_display().unwrap();
    con.take_ownership().unwrap()
};
// SAFETY: We took the display from a freshly created Connection so it is valid
//         and has no queues or proxies attached.
let _con = unsafe { lib.wrap_owned_pointer(wl_display) };

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

Returns a reference to the Libwayland singleton.

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

Returns the last error that occurred on the connection, if any.

Since all errors are fatal, if this function returns an error, the connection can no longer be used.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
assert!(con.error().is_ok());

impl Connection

pub fn create_queue_with_data<T>( &self, name: &CStr, ) -> (QueueOwner, QueueWithData<T>)

where T: 'static,

Creates a new queue with mutable data.

This function is the same as Connection::create_queue except that event handlers attached to this queue can receive a &mut T. When dispatching the queue, a &mut T must be passed into one of the dispatcher functions of QueueWithData. The dispatcher functions declared on Queue cannot be used to dispatch this queue.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let (_queue_owner, _queue) = con.create_queue_with_data::<State>(c"queue name");

struct State {
    // ...
}

Examples found in repository

examples/get-registry-with-data/main.rs (line 25)

fn main() {
    let lib = Libwayland::open().unwrap();
    let con = lib.connect_to_default_display().unwrap();
    let (_queue, queue) = con.create_queue_with_data::<State>(c"get-registry");

    // Create a new registry that will receive the globals and can later be used to
    // bind them.
    let mut state = State {
        registry: queue.display::<WlDisplay>().get_registry(),
        globals: vec![],
    };

    // 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.
    proxy::set_event_handler(
        &state.registry,
        WlRegistry::on_global(|state: &mut State, _, name, interface, version| {
            state.globals.push(Global {
                name,
                interface: interface.to_string(),
                version,
            });
        }),
    );
    queue.dispatch_roundtrip_blocking(&mut state).unwrap();

    println!("{:#?}", state.globals);
}

pub fn create_local_queue_with_data<T>( &self, name: &CStr, ) -> (QueueOwner, QueueWithData<T>)

where T: 'static,

Creates a new queue with mutable data.

This function is the same as Connection::create_local_queue except that event handlers attached to this queue can receive a &mut T. When dispatching the queue, a &mut T must be passed into one of the dispatcher functions of QueueWithData. The dispatcher functions declared on Queue cannot be used to dispatch this queue.

Example

let lib = Libwayland::open().unwrap();
let con = lib.connect_to_default_display().unwrap();
let (_queue_owner, _queue) = con.create_local_queue_with_data::<State>(c"queue name");

struct State {
    // ...
}

impl Connection

pub fn create_queue(&self, name: &CStr) -> QueueOwner

Creates a new queue.

The new queue is not a local queue. It can be dispatched from any thread. Event handlers attached to this queue must implement Send. See the documentation of Queue for a description of local and non-local queues.

Example

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

Examples found in repository

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

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

    let (_, snapshot) = get_registry_snapshot(&queue);
    println!("{:#?}", snapshot);
}

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

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 fn create_local_queue(&self, name: &CStr) -> QueueOwner

Creates a new local queue.

The new queue is a local queue. It can only be dispatched from the thread that called this function. See the documentation of Queue for a description of local and non-local queues.

Example

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

Examples found in repository

examples/async-wait/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-wait");

    create_sync(&queue, 1);

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

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

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 12)

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 29)

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 14)

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

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

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

Additional examples can be found in:

• examples/simple-window/../common/simple_window.rs

pub fn borrow_default_queue(&self) -> BorrowedQueue

Creates a BorrowedQueue representing the default queue.

pub unsafe fn borrow_foreign_queue( &self, queue: NonNull<wl_event_queue>, ) -> BorrowedQueue

Creates a BorrowedQueue representing a wl_event_queue pointer.

Safety

• The queue must be valid and stay valid for the lifetime of the BorrowedQueue.
• The queue must belong to this connection.

Trait Implementations

impl Clone for Connection

fn clone(&self) -> Connection

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Connection

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

Formats the value using the given formatter.

impl PartialEq for Connection

fn eq(&self, other: &Self) -> 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 Connection