API Reference

Listener(proxy, callbacks::ListenerCallbacks, data = nothing)

Create a listener object which ensures that all the memory used by a set of callbacks will remain valid as long as the listener is valid.

User-provided data may be:

• nothing (default), in which case the user data provided to Wayland will be C_NULL.
• Ptr, in which case it will be assumed that the pointer will remain valid. Loads to this data should be done manually by the user in the callback code, as retrieve_data makes a few assumptions as to how the pointer was obtained.
• Mutable data, in which case its pointer will obtained via pointer_from_objref and retrieve_data will use unsafe_pointer_to_objref.
• Immutable data, in which case a Ref will wrap the data and a pointer to this reference will be passed in as user data. Loads with retrieve_data will use Base.unsafe_load.

For the callbacks to be active, you must register the listener. Read the documentation of register carefully for more information about managing the listener's lifetime, which is vital in order for the callbacks not to cause undefined behavior.

wl_argument

Protocol message argument data types

This union represents all of the argument types in the Wayland protocol wire format. The protocol implementation uses wl_argument within its marshalling machinery for dispatching messages between a client and a compositor.

See also

wl_message, wl_interface, <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-wire-Format">Wire Format</a>

wl_array

wl_array

Dynamic array

A wl_array is a dynamic array that can only grow until released. It is intended for relatively small allocations whose size is variable or not known in advance. While construction of a wl_array does not require all elements to be of the same size, wl_array_for_each() does require all elements to have the same type and size.

Dispatcher function type alias

A dispatcher is a function that handles the emitting of callbacks in client code. For programs directly using the C library, this is done by using libffi to call function pointers. When binding to languages other than C, dispatchers provide a way to abstract the function calling process to be friendlier to other function calling systems.

A dispatcher takes five arguments: The first is the dispatcher-specific implementation associated with the target object. The second is the object upon which the callback is being invoked (either wl_proxy or wl_resource). The third and fourth arguments are the opcode and the wl_message corresponding to the callback. The final argument is an array of arguments received from the other process via the wire protocol.

Parameters

• "const: void *" Dispatcher-specific implementation data
• "void: *" Callback invocation target (wl_proxy or wl_resource)
• uint32_t: Callback opcode
• "const: struct wl_message *" Callback message signature
• "union: wl_argument *" Array of received arguments

Returns

0 on success, or -1 on failure

wl_display

Represents a connection to the compositor and acts as a proxy to the wl_display singleton object.

A wl_display object represents a client connection to a Wayland compositor. It is created with either wldisplayconnect() or wldisplayconnecttofd(). A connection is terminated using wldisplaydisconnect().

A wl_display is also used as the wlproxy for the [`wldisplay`](@ref) singleton object on the compositor side.

A wl_display object handles all the data sent from and to the compositor. When a wlproxy marshals a request, it will write its wire representation to the display's write buffer. The data is sent to the compositor when the client calls wldisplay_flush().

Incoming data is handled in two steps: queueing and dispatching. In the queue step, the data coming from the display fd is interpreted and added to a queue. On the dispatch step, the handler for the incoming event set by the client on the corresponding wl_proxy is called.

A wl_display has at least one event queue, called the <em>default queue</em>. Clients can create additional event queues with wldisplaycreatequeue() and assign wlproxy's to it. Events occurring in a particular proxy are always queued in its assigned queue. A client can ensure that a certain assumption, such as holding a lock or running from a given thread, is true when a proxy event handler is called by assigning that proxy to an event queue and making sure that this queue is only dispatched when the assumption holds.

The default queue is dispatched by calling wldisplaydispatch(). This will dispatch any events queued on the default queue and attempt to read from the display fd if it's empty. Events read are then queued on the appropriate queues according to the proxy assignment.

A user created queue is dispatched with wldisplaydispatchqueue(). This function behaves exactly the same as [`wldisplay_dispatch`](@ref)() but it dispatches given queue instead of the default queue.

A real world example of event queue usage is Mesa's implementation of eglSwapBuffers() for the Wayland platform. This function might need to block until a frame callback is received, but dispatching the default queue could cause an event handler on the client to start drawing again. This problem is solved using another event queue, so that only the events handled by the EGL code are dispatched during the block.

This creates a problem where a thread dispatches a non-default queue, reading all the data from the display fd. If the application would call poll(2) after that it would block, even though there might be events queued on the default queue. Those events should be dispatched with wldisplaydispatchpending() or wldisplaydispatchqueue_pending() before flushing and blocking.

A filter function for wl_global objects

A filter function enables the server to decide which globals to advertise to each client.

When a wl_global filter is set, the given callback function will be called during wl_global advertisement and binding.

This function should return true if the global object should be made visible to the client or false otherwise.

Parameters

• client: The client object
• global: The global object to show or hide
• data: The user data pointer

File descriptor dispatch function type

Functions of this type are used as callbacks for file descriptor events.

Parameters

• fd: The file descriptor delivering the event.
• mask: Describes the kind of the event as a bitwise-or of: WL_EVENT_READABLE, WL_EVENT_WRITABLE, WL_EVENT_HANGUP, WL_EVENT_ERROR.
• data: The user data argument of the related wl_event_loop_add_fd() call.

Returns

If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

See also

wl_event_loop_add_fd() wleventsource

Idle task function type

Functions of this type are used as callbacks before blocking in wl_event_loop_dispatch().

Parameters

• data: The user data argument of the related wl_event_loop_add_idle() call.

See also

wl_event_loop_add_idle() wl_event_loop_dispatch() wleventsource

Signal dispatch function type

Functions of this type are used as callbacks for (POSIX) signals.

Parameters

• signal_number:
• data: The user data argument of the related wl_event_loop_add_signal() call.

Returns

If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

See also

wl_event_loop_add_signal() wleventsource

Timer dispatch function type

Functions of this type are used as callbacks for timer expiry.

Parameters

• data: The user data argument of the related wl_event_loop_add_timer() call.

Returns

If the event source is registered for re-check with wl_event_source_check(): 0 for all done, 1 for needing a re-check. If not registered, the return value is ignored and should be zero.

See also

wl_event_loop_add_timer() wleventsource

wl_event_queue

A queue for wl_proxy object events.

Event queues allows the events on a display to be handled in a thread-safe manner. See wl_display for details.

Fixed-point number

A wl_fixed_t is a 24.8 signed fixed-point number with a sign bit, 23 bits of integer precision and 8 bits of decimal precision. Consider wl_fixed_t as an opaque struct with methods that facilitate conversion to and from double and int types.

wl_interface

Protocol object interface

A wl_interface describes the API of a protocol object defined in the Wayland protocol specification. The protocol implementation uses a wl_interface within its marshalling machinery for encoding client requests.

The name of a wl_interface is the name of the corresponding protocol interface, and version represents the version of the interface. The members method_count and event_count represent the number of methods (requests) and events in the respective wl_message members.

For example, consider a protocol interface foo, marked as version 1, with two requests and one event.

{.xml}
 <interface name="foo" version="1">
   <request name="a"></request>
   <request name="b"></request>
   <event name="c"></event>
 </interface>

Given two wl_message arrays foo_requests and foo_events, a wl_interface for foo might be:

 struct wl_interface foo_interface = {
         "foo", 1,
         2, foo_requests,
         1, foo_events
 };

See also

wl_message, wl_proxy, <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Interfaces">Interfaces</a>, <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Versioning">Versioning</a>

wl_iterator_result

Return value of an iterator function

See also

wl_client_for_each_resource_iterator_func_t, wl_client_for_each_resource

wl_list

wl_list

Doubly-linked list

On its own, an instance of struct [wllist](@ref) represents the sentinel head of a doubly-linked list, and must be initialized using [`wllist_init](@ref)(). When empty, the list head'snextandprevmembers point to the list head itself, otherwisenextreferences the first element in the list, andprev` refers to the last element in the list.

Use the struct [wllist](@ref) type to represent both the list head and the links between elements within the list. Use [`wllist_empty`](@ref)() to determine if the list is empty in O(1).

All elements in the list must be of the same type. The element type must have a struct [wllist](@ref) member, often named link by convention. Prior to insertion, there is no need to initialize an element's link - invoking [`wllistinit](@ref)() on an individual list element'sstruct [`wllist](@ref) member is unnecessary if the very next operation is wl_list_insert(). However, a common idiom is to initialize an element's link prior to removal - ensure safety by invoking wl_list_init() before wl_list_remove().

Consider a list reference struct [wllist`](@ref) foo\list, an element type asstruct element, and an element's link member asstruct wl_list link`.

The following code initializes a list and adds three elements to it.

 struct wl_list foo_list;
 struct element {
         int foo;
         struct wl_list link;
 };
 struct element e1, e2, e3;
 wl_list_init(&foo_list);
 wl_list_insert(&foo_list, &e1.link);   // e1 is the first element
 wl_list_insert(&foo_list, &e2.link);   // e2 is now the first element
 wl_list_insert(&e2.link, &e3.link); // insert e3 after e2

The list now looks like <em>[e2, e3, e1]</em>.

The wl_list API provides some iterator macros. For example, to iterate a list in ascending order:

 struct element *e;
 wl_list_for_each(e, foo_list, link) {
         do_something_with_element(e);
 }

See the documentation of each iterator for details.

See also

http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/include/linux/list.h

wl_listener

wl_listener

A single listener for Wayland signals

wl_listener provides the means to listen for wl_signal notifications. Many Wayland objects use wl_listener for notification of significant events like object destruction.

Clients should create wl_listener objects manually and can register them as listeners to signals using #wl_signal_add, assuming the signal is directly accessible. For opaque structs like wl_event_loop, adding a listener should be done through provided accessor methods. A listener can only listen to one signal at a time.

 struct wl_listener your_listener;
 your_listener.notify = your_callback_method;
 // Direct access
 wl_signal_add(&some_object->destroy_signal, &your_listener);
 // Accessor access
 wl_event_loop *loop = ...;
 wl_event_loop_add_destroy_listener(loop, &your_listener);

If the listener is part of a larger struct, #wl_container_of can be used to retrieve a pointer to it:

 void your_listener(struct wl_listener *listener, void *data)
 {
 	struct your_data *data;
 	your_data = wl_container_of(listener, data, your_member_name);
 }

If you need to remove a listener from a signal, use wl_list_remove().

 wl_list_remove(&your_listener.link);

See also

wl_signal

Log function type alias

The C implementation of the Wayland protocol abstracts the details of logging. Users may customize the logging behavior, with a function conforming to the wl_log_func_t type, via wl_log_set_handler_client and wl_log_set_handler_server.

A wl_log_func_t must conform to the expectations of vprintf, and expects two arguments: a string to write and a corresponding variable argument list. While the string to write may contain format specifiers and use values in the variable argument list, the behavior of any wl_log_func_t depends on the implementation.

Parameters

• "const: char *" String to write to the log, containing optional format specifiers
• "va_list": Variable argument list

See also

wl_log_set_handler_client, wl_log_set_handler_server

wl_message

Protocol message signature

A wl_message describes the signature of an actual protocol message, such as a request or event, that adheres to the Wayland protocol wire format. The protocol implementation uses a wl_message within its demarshal machinery for decoding messages between a compositor and its clients. In a sense, a wl_message is to a protocol message like a class is to an object.

The name of a wl_message is the name of the corresponding protocol message.

The signature is an ordered list of symbols representing the data types of message arguments and, optionally, a protocol version and indicators for nullability. A leading integer in the signature indicates the _since_ version of the protocol message. A ? preceding a data type symbol indicates that the following argument type is nullable. While it is a protocol violation to send messages with non-nullable arguments set to NULL, event handlers in clients might still get called with non-nullable object arguments set to NULL. This can happen when the client destroyed the object being used as argument on its side and an event referencing that object was sent before the server knew about its destruction. As this race cannot be prevented, clients should - as a general rule - program their event handlers such that they can handle object arguments declared non-nullable being NULL gracefully.

When no arguments accompany a message, signature is an empty string.

Symbols:

• i: int * u: uint * f: fixed * s: string * o: object * n: new_id * a: array * h: fd * ?: following argument is nullable

While demarshaling primitive arguments is straightforward, when demarshaling messages containing object or new_id arguments, the protocol implementation often must determine the type of the object. The types of a wl_message is an array of wl_interface references that correspond to o and n arguments in signature, with NULL placeholders for arguments with non-object types.

Consider the protocol event wl_display delete_id that has a single uint argument. The wl_message is:

 { "delete_id", "u", [NULL] }

Here, the message name is "delete\_id", the signature is "u", and the argument types is [NULL], indicating that the uint argument has no corresponding wl_interface since it is a primitive argument.

In contrast, consider a wl_foo interface supporting protocol request bar that has existed since version 2, and has two arguments: a uint and an object of type wl_baz_interface that may be NULL. Such a wl_message might be:

 { "bar", "2u?o", [NULL, &wl_baz_interface] }

Here, the message name is "bar", and the signature is "2u?o". Notice how the 2 indicates the protocol version, the u indicates the first argument type is uint, and the ?o indicates that the second argument is an object that may be NULL. Lastly, the argument types array indicates that no wl_interface corresponds to the first argument, while the type wl_baz_interface corresponds to the second argument.

See also

wl_argument, wl_interface, <a href="https://wayland.freedesktop.org/docs/html/ch04.html#sect-Protocol-Wire-Format">Wire Format</a>

wl_object

A protocol object.

A wl_object is an opaque struct identifying the protocol object underlying a wl_proxy or wl_resource.

wl_proxy

Represents a protocol object on the client side.

A wl_proxy acts as a client side proxy to an object existing in the compositor. The proxy is responsible for converting requests made by the clients with wlproxymarshal() into Wayland's wire format. Events coming from the compositor are also handled by the proxy, which will in turn call the handler set with wlproxyadd_listener().

wl_signal

wl_signal

A source of a type of observable event

Signals are recognized points where significant events can be observed. Compositors as well as the server can provide signals. Observers are wl_listener's that are added through #wl_signal_add. Signals are emitted using #wl_signal_emit, which will invoke all listeners until that listener is removed by wl_list_remove() (or whenever the signal is destroyed).

See also

wl_listener for more information on using wl_signal

Register a listener with optional user-data data.

If keep_alive is set to true (default), then the listener will be kept on a global concurrent data structure to prevent it from being garbage-collected. You can manually remove the listener from this state by calling finalize(listener) (which will be a no-op if the listener was never preserved via a call to register(...,keep_alive = true).

Retrieve data from a pointer, assuming that it is derived from the provided type.

data must not be null, will be assumed to point to valid memory and will be assumed to have been handled by data_reference and get_dataptr. If data was provided as a pointer to a Listener,

wl_array_add(array, size)

Increases the size of the array by size bytes.

wl_array

Parameters

• array: Array whose size is to be increased
• size: Number of bytes to increase the size of the array by

Returns

A pointer to the beginning of the newly appended space, or NULL when resizing fails.

wl_array_copy(array, source)

Copies the contents of source to array.

wl_array

Parameters

• array: Destination array to copy to
• source: Source array to copy from

Returns

0 on success, or -1 on failure

wl_array_init(array)

Initializes the array.

wl_array

Parameters

• array: Array to initialize

wl_array_release(array)

Releases the array data.

wl_array

Parameters

• array: Array whose data is to be released

wl_event_loop_create()

wl_event_source

An abstract event source

This is the generic type for fd, timer, signal, and idle sources. Functions that operate on specific source types must not be used with a different type, even if the function signature allows it.

wl_fixed_from_double(d)

Converts a floating-point number to a fixed-point number.

Parameters

• d: Floating-point number to convert

Returns

Fixed-point representation of the floating-point argument

wl_fixed_from_int(i)

Converts an integer to a fixed-point number.

Parameters

• i: Integer to convert

Returns

Fixed-point representation of the integer argument

wl_fixed_to_double(f)

Converts a fixed-point number to a floating-point number.

Parameters

• f: Fixed-point number to convert

Returns

Floating-point representation of the fixed-point argument

wl_fixed_to_int(f)

Converts a fixed-point number to an integer.

Parameters

• f: Fixed-point number to convert

Returns

Integer component of the fixed-point argument

wl_list_empty(list)

Determines if the list is empty.

wl_list

Parameters

• list: List whose emptiness is to be determined

Returns

1 if empty, or 0 if not empty

wl_list_init(list)

Initializes the list.

wl_list

Parameters

• list: List to initialize

wl_list_insert(list, elm)

Inserts an element into the list, after the element represented by list. When list is a reference to the list itself (the head), set the containing struct of elm as the first element in the list.

wl_list

Parameters

• list: List element after which the new element is inserted
• elm: Link of the containing struct to insert into the list

wl_list_insert_list(list, other)

Inserts all of the elements of one list into another, after the element represented by list.

wl_list

Parameters

• list: List element after which the other list elements will be inserted
• other: List of elements to insert

wl_list_length(list)

Determines the length of the list.

wl_list

Parameters

• list: List whose length is to be determined

Returns

Number of elements in the list

wl_list_remove(elm)

Removes an element from the list.

wl_list

Parameters

• elm: Link of the containing struct to remove from the list

wl_signal_add(signal, listener)

Add the specified listener to this signal.

wl_signal

Parameters

• signal: The signal that will emit events to the listener
• listener: The listener to add

wl_signal_emit(signal, data)

Emits this signal, notifying all registered listeners.

wl_signal

Parameters

• signal: The signal object that will emit the signal
• data: The data that will be emitted with the signal

wl_signal_get(signal, notify)

Gets the listener struct for the specified callback.

wl_signal

Parameters

• signal: The signal that contains the specified listener
• notify: The listener that is the target of this search

Returns

the list item that corresponds to the specified listener, or NULL if none was found

wl_signal_init(signal)

Initialize a new wl_signal for use.

wl_signal

Parameters

• signal: The signal that will be initialized