Module proxy 

Wayland proxy objects and helpers.

Proxies represent objects in the wayland protocol. Libwayland uses wl_proxy pointers to represent proxies and wl-client provides safe types to handle them.

Proxy types

There are four different types of proxies across two dimensions:

• In libwayland:
  • A wrapper wl_proxy is a proxy that was created by calling the wl_proxy_create_wrapper function.
  • A plain wl_proxy is any other proxy.
• In wl-client:
  • An owned proxy is a proxy that will destroy the underlying wl_proxy when it is dropped.
  • A borrowed proxy is a proxy that only references a wl_proxy and will never be used to destroy it.

Therefore, each proxy is

• an owned wrapper proxy,
• an owned plain proxy,
• a borrowed wrapper proxy, or
• a borrowed plain proxy.

Owned proxies

Owned proxies are proxies created by wl-client. They have a Queue, also created by wl-client, which can be accessed by calling queue.

When an owned proxy is used to create a new wayland object, the function returns a new owned proxy that is assigned to the same queue as its parent.

An owned proxy can be used to destroy the proxy by sending a destructor request or by using the destroy function. Owned proxies are implicitly destroyed with the destroy function in the following situations:

• When the last reference to the owned proxy is dropped.
• When the QueueOwner owning the proxy’s queue is dropped. This is explained in detail in the documentation of Queue.

Borrowed proxies

Borrowed proxies might or might not have been created by wl-client. Each owned proxy derefs to a borrowed proxy but a borrowed proxy can also be created from raw wl_proxy pointers.

Since the ownership of these proxies is unknown, they cannot be used to to destroy the proxy.

If a request is sent on a borrowed proxy that creates a new wayland object, the caller must also pass in a Queue. The returned owned proxy will be assigned to this queue.

Creating wrapper proxies

When working with wayland objects created by foreign code, the foreign code usually shares raw wl_proxy pointers. Given a Queue, it is possible to create a new owned wrapper proxy by calling Queue::wrap_wl_proxy.

Setting proxy event handlers

Event handlers can be attached to owned plain proxies by using one of the following functions:

• set_event_handler - for Send + 'static event handlers
• set_event_handler_local - for 'static event handlers
• set_event_handler_no_op
• Scope::set_event_handler - for Send + 'scope event handlers
• Scope::set_event_handler_local - for 'scope event handlers

The _local variant allows setting event handlers that do not implement Send. The _no_op variant can be used to destroy compositor-created resources if the application is not otherwise interested in events.

Event handlers cannot be set on owned wrapper proxies.

For each proxy, the event handler can only be set once and once set it cannot be unset.

Modules

low_level

Low-level proxy APIs.

Structs

BorrowedProxyLock

A lock that ensures that a UntypedBorrowedProxy is not changed.

Traits

BorrowedProxy

A borrowed proxy.

OwnedProxy

An owned proxy.

Functions

destroy

Destroys a proxy without sending a wayland message.

id

Returns the wayland object ID of a proxy.

is_destroyed

Returns whether this proxy is destroyed.

is_not_destroyed

Returns whether this proxy is not destroyed.

lock

Locks the proxy for concurrent destruction.

queue

Returns the queue of a proxy.

set_event_handler

Sets the event handler of the proxy.

set_event_handler_local

Sets the !Send event handler of the proxy.

set_event_handler_no_op

Sets the event handler of the proxy to ignore all events.

version

Returns the version of this proxy object.

wl_proxy

Returns the wl_proxy pointer of a proxy.