Product SiteDocumentation Site

Chapter 5. Wayland Library

5.1. Client API
5.2. Server API
The open-source reference implementation of Wayland protocol is split in two C libraries, libwayland-server and libwayland-client. Their main responsibility is to handle the Inter-process communication (IPC) with each other, therefore guaranteeing the protocol objects marshaling and messages synchronization.
This Chapter describes in detail each library's methods and their helpers, aiming implementors who can use for building Wayland clients and servers; respectively at Section 5.1, “Client API” and Section 5.2, “Server API”.

5.1. Client API

Following is the Wayland library classes for the Client (libwayland-client). Note that most of the procedures are related with IPC, which is the main responsibility of the library.
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 wl_display_connect() or wl_display_connect_to_fd(). A connection is terminated using wl_display_disconnect().
A wl_display is also used as the wl_proxy for the wl_display singleton object on the compositor side.
A wl_display object handles all the data sent from and to the compositor. When a wl_proxy 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 wl_display_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 main queue. Clients can create additional event queues with wl_display_create_queue() and assign wl_proxy'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 main queue is dispatched by calling wl_display_dispatch(). This will dispatch any events queued on the main queue and attempt to read from the display fd if its empty. Events read are then queued on the appropriate queues according to the proxy assignment. Calling that function makes the calling thread the main thread.
A user created queue is dispatched with wl_display_dispatch_queue(). If there are no events to dispatch this function will block. If this is called by the main thread, this will attempt to read data from the display fd and queue any events on the appropriate queues. If calling from any other thread, the function will block until the main thread queues an event on the queue being dispatched.
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 main 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 the main thread dispatches a non-main 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 main queue. Those events should be dispatched with wl_display_dispatch_pending() before flushing and blocking.
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.
wl_list - doubly-linked list
The list head is of "struct wl_list" type, and must be initialized using wl_list_init(). All entries in the list must be of the same type. The item type must have a "struct wl_list" member. This member will be initialized by wl_list_insert(). There is no need to call wl_list_init() on the individual item. To query if the list is empty in O(1), use wl_list_empty().
Let's call the list reference "struct wl_list foo_list", the item type as "item_t", and the item member as "struct wl_list link".
The following code will initialize a list: struct wl_list foo_list; struct item_t { int foo; struct wl_list link; }; struct item_t item1, item2, item3; wl_list_init(&foo_list); wl_list_insert(&foo_list, &item1.link); Pushes item1 at the head wl_list_insert(&foo_list, &item2.link); Pushes item2 at the head wl_list_insert(&item2.link, &item3.link); Pushes item3 after item2
The list now looks like [item2, item3, item1]
Will iterate the list in ascending order: item_t *item; wl_list_for_each(item, foo_list, link) { Do_something_with_item(item);
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 wl_proxy_marshal() 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 wl_proxy_add_listener().
With the exception of function wl_proxy_set_queue(), functions accessing a wl_proxy are not normally used by client code. Clients should normally use the higher level interface generated by the scanner to interact with compositor objects.
Methods for the respective classes.
wl_display_create_queue - Create a new event queue for this display.
struct wl_event_queue * wl_display_create_queue(struct wl_display *display)
display
The display context object
Returns:
A new event queue associated with this display or NULL on failure.
wl_display_connect_to_fd - Connect to Wayland display on an already open fd.
struct wl_display * wl_display_connect_to_fd(int fd)
fd
The fd to use for the connection
Returns:
A wl_display object or NULL on failure
The wl_display takes ownership of the fd and will close it when the display is destroyed. The fd will also be closed in case of failure.
wl_display_connect - Connect to a Wayland display.
struct wl_display * wl_display_connect(const char *name)
name
Name of the Wayland display to connect to
Returns:
A wl_display object or NULL on failure
Connect to the Wayland display named name. If name is NULL, its value will be replaced with the WAYLAND_DISPLAY environment variable if it is set, otherwise display "wayland-0" will be used.
wl_display_disconnect - Close a connection to a Wayland display.
void wl_display_disconnect(struct wl_display *display)
display
The display context object
Close the connection to display and free all resources associated with it.
wl_display_get_fd - Get a display context's file descriptor.
int wl_display_get_fd(struct wl_display *display)
display
The display context object
Returns:
Display object file descriptor
Return the file descriptor associated with a display so it can be integrated into the client's main loop.
wl_display_roundtrip - Block until all pending request are processed by the server.
int wl_display_roundtrip(struct wl_display *display)
display
The display context object
Returns:
The number of dispatched events on success or -1 on failure
Blocks until the server process all currently issued requests and sends out pending events on all event queues.
wl_display_read_events - Read events from display file descriptor.
int wl_display_read_events(struct wl_display *display)
display
The display context object
Returns:
0 on success or -1 on error. In case of error errno will be set accordingly
This will read events from the file descriptor for the display. This function does not dispatch events, it only reads and queues events into their corresponding event queues. If no data is avilable on the file descriptor, wl_display_read_events() returns immediately. To dispatch events that may have been queued, call wl_display_dispatch_pending() or wl_display_dispatch_queue_pending().
Before calling this function, wl_display_prepare_read() must be called first.
wl_display_prepare_read - Prepare to read events after polling file descriptor.
int wl_display_prepare_read(struct wl_display *display)
display
The display context object
Returns:
0 on success or -1 if event queue was not empty
This function must be called before reading from the file descriptor using wl_display_read_events(). Calling wl_display_prepare_read() announces the calling threads intention to read and ensures that until the thread is ready to read and calls wl_display_read_events(), no other thread will read from the file descriptor. This only succeeds if the event queue is empty though, and if there are undispatched events in the queue, -1 is returned and errno set to EAGAIN.
If a thread successfully calls wl_display_prepare_read(), it must either call wl_display_read_events() when it's ready or cancel the read intention by calling wl_display_cancel_read().
Use this function before polling on the display fd or to integrate the fd into a toolkit event loop in a race-free way. Typically, a toolkit will call wl_display_dispatch_pending() before sleeping, to make sure it doesn't block with unhandled events. Upon waking up, it will assume the file descriptor is readable and read events from the fd by calling wl_display_dispatch(). Simplified, we have:
wl_display_dispatch_pending(display); wl_display_flush(display); poll(fds, nfds, -1); wl_display_dispatch(display);
There are two races here: first, before blocking in poll(), the fd could become readable and another thread reads the events. Some of these events may be for the main queue and the other thread will queue them there and then the main thread will go to sleep in poll(). This will stall the application, which could be waiting for a event to kick of the next animation frame, for example.
The other race is immediately after poll(), where another thread could preempt and read events before the main thread calls wl_display_dispatch(). This call now blocks and starves the other fds in the event loop.
A correct sequence would be:
while (wl_display_prepare_read(display) != 0) wl_display_dispatch_pending(display); wl_display_flush(display); poll(fds, nfds, -1); wl_display_read_events(display); wl_display_dispatch_pending(display);
Here we call wl_display_prepare_read(), which ensures that between returning from that call and eventually calling wl_display_read_events(), no other thread will read from the fd and queue events in our queue. If the call to wl_display_prepare_read() fails, we dispatch the pending events and try again until we're successful.
wl_display_cancel_read - Release exclusive access to display file descriptor.
void wl_display_cancel_read(struct wl_display *display)
display
The display context object
This releases the exclusive access. Useful for canceling the lock when a timed out poll returns fd not readable and we're not going to read from the fd anytime soon.
wl_display_dispatch_queue - Dispatch events in an event queue.
int wl_display_dispatch_queue(struct wl_display *display, struct wl_event_queue *queue)
display
The display context object
queue
The event queue to dispatch
Returns:
The number of dispatched events on success or -1 on failure
Dispatch all incoming events for objects assigned to the given event queue. On failure -1 is returned and errno set appropriately.
This function blocks if there are no events to dispatch. If calling from the main thread, it will block reading data from the display fd. For other threads this will block until the main thread queues events on the queue passed as argument.
wl_display_dispatch_queue_pending - Dispatch pending events in an event queue.
int wl_display_dispatch_queue_pending(struct wl_display *display, struct wl_event_queue *queue)
display
The display context object
queue
The event queue to dispatch
Returns:
The number of dispatched events on success or -1 on failure
Dispatch all incoming events for objects assigned to the given event queue. On failure -1 is returned and errno set appropriately. If there are no events queued, this function returns immediately.
  • Since: 1.0.2
wl_display_dispatch - Process incoming events.
int wl_display_dispatch(struct wl_display *display)
display
The display context object
Returns:
The number of dispatched events on success or -1 on failure
Dispatch the display's main event queue.
If the main event queue is empty, this function blocks until there are events to be read from the display fd. Events are read and queued on the appropriate event queues. Finally, events on the main event queue are dispatched.
Note: It is not possible to check if there are events on the main queue or not. For dispatching main queue events without blocking, see wl_display_dispatch_pending().Calling this will release the display file descriptor if this thread acquired it using wl_display_acquire_fd().
  • See also: wl_display_dispatch_pending() wl_display_dispatch_queue()
wl_display_dispatch_pending - Dispatch main queue events without reading from the display fd.
int wl_display_dispatch_pending(struct wl_display *display)
display
The display context object
Returns:
The number of dispatched events or -1 on failure
This function dispatches events on the main event queue. It does not attempt to read the display fd and simply returns zero if the main queue is empty, i.e., it doesn't block.
This is necessary when a client's main loop wakes up on some fd other than the display fd (network socket, timer fd, etc) and calls wl_display_dispatch_queue() from that callback. This may queue up events in the main queue while reading all data from the display fd. When the main thread returns to the main loop to block, the display fd no longer has data, causing a call to poll(2) (or similar functions) to block indefinitely, even though there are events ready to dispatch.
To proper integrate the wayland display fd into a main loop, the client should always call wl_display_dispatch_pending() and then wl_display_flush() prior to going back to sleep. At that point, the fd typically doesn't have data so attempting I/O could block, but events queued up on the main queue should be dispatched.
A real-world example is a main loop that wakes up on a timerfd (or a sound card fd becoming writable, for example in a video player), which then triggers GL rendering and eventually eglSwapBuffers(). eglSwapBuffers() may call wl_display_dispatch_queue() if it didn't receive the frame event for the previous frame, and as such queue events in the main queue.
Note: Calling this makes the current thread the main one.
  • See also: wl_display_dispatch() wl_display_dispatch_queue() wl_display_flush()
wl_display_get_error - Retrieve the last error that occurred on a display.
int wl_display_get_error(struct wl_display *display)
display
The display context object
Returns:
The last error that occurred on display or 0 if no error occurred
Return the last error that occurred on the display. This may be an error sent by the server or caused by the local client.
Note: Errors are fatal. If this function returns non-zero the display can no longer be used.
wl_display_flush - Send all buffered requests on the display to the server.
int wl_display_flush(struct wl_display *display)
display
The display context object
Returns:
The number of bytes sent on success or -1 on failure
Send all buffered data on the client side to the server. Clients should call this function before blocking. On success, the number of bytes sent to the server is returned. On failure, this function returns -1 and errno is set appropriately.
wl_display_flush() never blocks. It will write as much data as possible, but if all data could not be written, errno will be set to EAGAIN and -1 returned. In that case, use poll on the display file descriptor to wait for it to become writable again.
wl_event_queue_destroy - Destroy an event queue.
void wl_event_queue_destroy(struct wl_event_queue *queue)
queue
The event queue to be destroyed
Destroy the given event queue. Any pending event on that queue is discarded.
The wl_display object used to create the queue should not be destroyed until all event queues created with it are destroyed with this function.
wl_proxy_create - Create a proxy object with a given interface.
struct wl_proxy * wl_proxy_create(struct wl_proxy *factory, const struct wl_interface *interface)
factory
Factory proxy object
interface
Interface the proxy object should use
Returns:
A newly allocated proxy object or NULL on failure
This function creates a new proxy object with the supplied interface. The proxy object will have an id assigned from the client id space. The id should be created on the compositor side by sending an appropriate request with wl_proxy_marshal().
The proxy will inherit the display and event queue of the factory object.
Note: This should not normally be used by non-generated code.
  • See also: wl_display wl_event_queue wl_proxy_marshal()
wl_proxy_destroy - Destroy a proxy object.
void wl_proxy_destroy(struct wl_proxy *proxy)
proxy
The proxy to be destroyed
wl_proxy_add_listener - Set a proxy's listener.
int wl_proxy_add_listener(struct wl_proxy *proxy, void(**implementation)(void), void *data)
proxy
The proxy object
implementation
The listener to be added to proxy
data
User data to be associated with the proxy
Returns:
0 on success or -1 on failure
Set proxy's listener to implementation and its user data to data. If a listener has already been set, this function fails and nothing is changed.
implementation is a vector of function pointers. For an opcode n, implementation[n] should point to the handler of n for the given object.
wl_proxy_get_listener - Get a proxy's listener.
const void * wl_proxy_get_listener(struct wl_proxy *proxy)
proxy
The proxy object
Returns:
The address of the proxy's listener or NULL if no listener is set
Gets the address to the proxy's listener; which is the listener set with wl_proxy_add_listener.
This function is useful in client with multiple listeners on the same interface to allow the identification of which code to eexecute.
wl_proxy_add_dispatcher - Set a proxy's listener (with dispatcher)
int wl_proxy_add_dispatcher(struct wl_proxy *proxy, wl_dispatcher_func_t dispatcher, const void *implementation, void *data)
proxy
The proxy object
dispatcher
The dispatcher to be used for this proxy
implementation
The dispatcher-specific listener implementation
data
User data to be associated with the proxy
Returns:
0 on success or -1 on failure
Set proxy's listener to use dispatcher_func as its dispatcher and dispatcher_data as its dispatcher-specific implementation and its user data to data. If a listener has already been set, this function fails and nothing is changed.
The exact details of dispatcher_data depend on the dispatcher used. This function is intended to be used by language bindings, not user code.
wl_proxy_marshal - Prepare a request to be sent to the compositor.
void wl_proxy_marshal(struct wl_proxy *proxy, uint32_t opcode,...)
proxy
The proxy object
opcode
Opcode of the request to be sent
...
Extra arguments for the given request
Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer.
The example below creates a proxy object with the wl_surface_interface using a wl_compositor factory interface and sends the compositor.create_surface request using wl_proxy_marshal(). Note the id is the extra argument to the request as specified by the protocol.
*id=wl_proxy_create((structwl_proxy*)wl_compositor,
*&wl_surface_interface);
*wl_proxy_marshal((structwl_proxy*)wl_compositor,
*WL_COMPOSITOR_CREATE_SURFACE,id);
*
Note: This should not normally be used by non-generated code.
  • See also: wl_proxy_create()
wl_proxy_marshal_array - Prepare a request to be sent to the compositor.
void wl_proxy_marshal_array(struct wl_proxy *proxy, uint32_t opcode, union wl_argument *args)
proxy
The proxy object
opcode
Opcode of the request to be sent
args
Extra arguments for the given request
Translates the request given by opcode and the extra arguments into the wire format and write it to the connection buffer. This version takes an array of the union type wl_argument.
Note: This is intended to be used by language bindings and not in non-generated code.
  • See also: wl_proxy_marshal()
wl_proxy_set_user_data - Set the user data associated with a proxy.
void wl_proxy_set_user_data(struct wl_proxy *proxy, void *user_data)
proxy
The proxy object
user_data
The data to be associated with proxy
Set the user data associated with proxy. When events for this proxy are received, user_data will be supplied to its listener.
wl_proxy_get_user_data - Get the user data associated with a proxy.
void * wl_proxy_get_user_data(struct wl_proxy *proxy)
proxy
The proxy object
Returns:
The user data associated with proxy
wl_proxy_get_id - Get the id of a proxy object.
uint32_t wl_proxy_get_id(struct wl_proxy *proxy)
proxy
The proxy object
Returns:
The id the object associated with the proxy
wl_proxy_get_class - Get the interface name (class) of a proxy object.
const char * wl_proxy_get_class(struct wl_proxy *proxy)
proxy
The proxy object
Returns:
The interface name of the object associated with the proxy
wl_proxy_set_queue - Assign a proxy to an event queue.
void wl_proxy_set_queue(struct wl_proxy *proxy, struct wl_event_queue *queue)
proxy
The proxy object
queue
The event queue that will handle this proxy
Assign proxy to event queue. Events coming from proxy will be queued in queue instead of the display's main queue.
  • See also: wl_display_dispatch_queue()
wl_display_prepare_read_queue -
int wl_display_prepare_read_queue(struct wl_display *display, struct wl_event_queue *queue)
wl_log_set_handler_client -
void wl_log_set_handler_client(wl_log_func_t handler)
wl_list_init -
void wl_list_init(struct wl_list *list)
wl_list_insert -
void wl_list_insert(struct wl_list *list, struct wl_list *elm)
wl_list_remove -
void wl_list_remove(struct wl_list *elm)
wl_list_length -
int wl_list_length(const struct wl_list *list)
wl_list_empty -
int wl_list_empty(const struct wl_list *list)
wl_list_insert_list -
void wl_list_insert_list(struct wl_list *list, struct wl_list *other)
wl_array_init -
void wl_array_init(struct wl_array *array)
wl_array_release -
void wl_array_release(struct wl_array *array)
wl_array_add -
void* wl_array_add(struct wl_array *array, size_t size)
wl_array_copy -
int wl_array_copy(struct wl_array *array, struct wl_array *source)
wl_map_init -
void wl_map_init(struct wl_map *map, uint32_t side)
wl_map_release -
void wl_map_release(struct wl_map *map)
wl_map_insert_new -
uint32_t wl_map_insert_new(struct wl_map *map, uint32_t flags, void *data)
wl_map_insert_at -
int wl_map_insert_at(struct wl_map *map, uint32_t flags, uint32_t i, void *data)
wl_map_reserve_new -
int wl_map_reserve_new(struct wl_map *map, uint32_t i)
wl_map_remove -
void wl_map_remove(struct wl_map *map, uint32_t i)
wl_map_lookup -
void* wl_map_lookup(struct wl_map *map, uint32_t i)
wl_map_lookup_flags -
uint32_t wl_map_lookup_flags(struct wl_map *map, uint32_t i)
wl_map_for_each -
void wl_map_for_each(struct wl_map *map, wl_iterator_func_t func, void *data)
wl_log -
void wl_log(const char *fmt,...)
wl_list_init -
void wl_list_init(struct wl_list *list)
wl_list_insert -
void wl_list_insert(struct wl_list *list, struct wl_list *elm)
wl_list_remove -
void wl_list_remove(struct wl_list *elm)
wl_list_length -
int wl_list_length(const struct wl_list *list)
wl_list_empty -
int wl_list_empty(const struct wl_list *list)
wl_list_insert_list -
void wl_list_insert_list(struct wl_list *list, struct wl_list *other)
wl_array_init -
void wl_array_init(struct wl_array *array)
wl_array_release -
void wl_array_release(struct wl_array *array)
wl_array_add -
void* wl_array_add(struct wl_array *array, size_t size)
wl_array_copy -
int wl_array_copy(struct wl_array *array, struct wl_array *source)