wl_display(3)

📦
version 1.26.0 · 15 versions
, in fedora 43, ubuntu stonking

💖 wl_display(3) — Library Functions Manual 💖

okay bestie, sit DOWN, because this is the wl_display page and she is long. This is part 1 of 4, so hydrate and let's go ✨

🌸 NAME 🌸

wl_display — it's a connection to the compositor, and it also moonlights as the proxy to the wl_display singleton object. dual career icon 💅

✨ SYNOPSIS ✨

#include <wayland-client-core.h>

🫶 Public Member Functions

  • struct wl_client * wl_client_create (struct wl_display *display, int fd)
  • struct wl_display * wl_display_create (void)
  • void wl_display_destroy (struct wl_display *display)
  • void wl_display_set_global_filter (struct wl_display *display, wl_display_global_filter_func_t filter, void *data)
  • uint32_t wl_display_get_serial (const struct wl_display *display)
  • uint32_t wl_display_next_serial (struct wl_display *display)
  • void wl_display_destroy_clients (struct wl_display *display)
  • void wl_display_set_default_max_buffer_size (struct wl_display *display, size_t max_buffer_size)
  • const char * wl_display_add_socket_auto (struct wl_display *display)
  • int wl_display_add_socket_fd (struct wl_display *display, int sock_fd)
  • int wl_display_remove_socket_fd (struct wl_display *display, int sock_fd)
  • int wl_display_add_socket (struct wl_display *display, const char *name)
  • struct wl_protocol_logger * wl_display_add_protocol_logger (struct wl_display *display, wl_protocol_logger_func_t func, void *user_data)
  • uint32_t * wl_display_add_shm_format (struct wl_display *display, uint32_t format)
  • struct wl_list * wl_display_get_client_list (struct wl_display *display)
  • struct wl_event_queue * wl_display_create_queue (struct wl_display *display)
  • struct wl_event_queue * wl_display_create_queue_with_name (struct wl_display *display, const char *name)
  • struct wl_display * wl_display_connect_to_fd (int fd)
  • struct wl_display * wl_display_connect (const char *name)
  • void wl_display_disconnect (struct wl_display *display)
  • int wl_display_get_fd (struct wl_display *display)
  • int wl_display_roundtrip_queue (struct wl_display *display, struct wl_event_queue *queue)
  • int wl_display_roundtrip (struct wl_display *display)
  • int wl_display_read_events (struct wl_display *display)
  • int wl_display_prepare_read_queue (struct wl_display *display, struct wl_event_queue *queue)
  • int wl_display_prepare_read (struct wl_display *display)
  • void wl_display_cancel_read (struct wl_display *display)
  • int wl_display_dispatch_queue_timeout (struct wl_display *display, struct wl_event_queue *queue, const struct timespec *timeout)
  • int wl_display_dispatch_queue (struct wl_display *display, struct wl_event_queue *queue)
  • int wl_display_dispatch_queue_pending (struct wl_display *display, struct wl_event_queue *queue)
  • int wl_display_dispatch_queue_pending_single (struct wl_display *display, struct wl_event_queue *queue)
  • int wl_display_dispatch (struct wl_display *display)
  • int wl_display_dispatch_pending (struct wl_display *display)
  • int wl_display_dispatch_pending_single (struct wl_display *display)
  • int wl_display_get_error (struct wl_display *display)
  • uint32_t wl_display_get_protocol_error (struct wl_display *display, const struct wl_interface **interface, uint32_t *id)
  • int wl_display_flush (struct wl_display *display)
  • void wl_display_set_max_buffer_size (struct wl_display *display, size_t max_buffer_size)

🎀 Data Fields

  • struct wl_event_loop * loop
  • bool run
  • uint32_t next_global_name
  • uint32_t serial
  • struct wl_list registry_resource_list
  • struct wl_list global_list
  • struct wl_list socket_list
  • struct wl_list client_list
  • struct wl_list protocol_loggers
  • struct wl_priv_signal destroy_signal
  • struct wl_priv_signal create_client_signal
  • struct wl_array additional_shm_formats
  • wl_display_global_filter_func_t global_filter
  • void * global_filter_data
  • int terminate_efd
  • struct wl_event_source * term_source
  • size_t max_buffer_size

👑 Detailed Description 👑

okay so. wl_display represents a connection to the compositor and acts as a proxy to the wl_display singleton object. that's the whole personality, fr fr.

A wl_display object represents a client connection to a Wayland compositor. You create it with either wl_display_connect() or wl_display_connect_to_fd(), and you end the connection with wl_display_disconnect(). birth, life, disconnect 💔

A wl_display is also used as the wl_proxy for the wl_display singleton object on the compositor side. yes, she contains multitudes.

A wl_display object handles all the data sent from and to the compositor. When a wl_proxy marshals a request, it writes its wire representation to the display's write buffer. The data actually gets sent to the compositor when the client calls wl_display_flush(). no flush, no delivery, that's the rule bestie 📬

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 default 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 — like 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. it's giving ✨controlled chaos✨

The default queue is dispatched by calling wl_display_dispatch(). 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 wl_display_dispatch_queue(). This function behaves exactly the same as wl_display_dispatch() but it dispatches the given queue instead of the default queue. same energy, different 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. see? queues are not just a vibe, they're a strategy 🧠

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 wl_display_dispatch_pending() or wl_display_dispatch_queue_pending() before flushing and blocking.

⚠️ okay this one is a real gotcha bestie: dispatch the pending stuff FIRST, then flush and block. if you block first you'll just sit there like 🧍‍♀️ wondering why nothing happens.

💜 Member Function Documentation 💜

🌟 struct wl_client * wl_client_create (struct wl_display * display, int fd)

Create a client for the given file descriptor

Parameters

  • display — The display object
  • fd — The file descriptor for the socket to the client

Returns

The new client object, or NULL on failure. 😭

Given a file descriptor corresponding to one end of a socket, this function will create a wl_client struct and add the new client to the compositor's client list. At that point, the client is initialized and ready to run, as if the client had connected to the server's listening socket. When the client eventually sends requests to the compositor, the wl_client argument to the request handler will be the wl_client returned from this function. it's like the client walked in through the front door, except you opened the door yourself 🚪✨

The other end of the socket can be passed to wl_display_connect_to_fd() on the client side, or used with the WAYLAND_SOCKET environment variable on the client side.

Listeners added with wl_display_add_client_created_listener() will be notified by this function after the client is fully constructed.

On failure this function sets errno accordingly and returns NULL.

On success, the new client object takes the ownership of the file descriptor. On failure, the ownership of the socket endpoint file descriptor is unchanged — it is the responsibility of the caller to perform cleanup, e.g. call close().

🫶 so on failure, that fd is still yours. do not ghost it. close it.

🌈 struct wl_protocol_logger * wl_display_add_protocol_logger (struct wl_display * display, wl_protocol_logger_func_t func, void * user_data)

Adds a new protocol logger.

When a new protocol message arrives or is sent from the server, all the protocol logger functions will be called, carrying the user_data pointer, the type of the message (request or event) and the actual message. The lifetime of the messages passed to the logger function ends when they return, so the messages cannot be stored and accessed later.

💀 bestie. DO NOT stash that message pointer. it's gone the second your logger returns. no cap.

errno is set on error.

Parameters

  • display — The display object
  • func — The function to call to log a new protocol message
  • user_data — The user data pointer to pass to func

Returns

The protocol logger object on success, NULL on failure.

See also

wl_protocol_logger_destroy

🦋 uint32_t * wl_display_add_shm_format (struct wl_display * display, uint32_t format)

Add support for a wl_shm pixel format

Parameters

  • display — The display object
  • format — The wl_shm pixel format to advertise

Returns

A pointer to the wl_shm format that was added to the list, or NULL if adding it to the list failed.

Add the specified wl_shm format to the list of formats the wl_shm object advertises when a client binds to it. Adding a format to the list means that clients will know that the compositor supports this format and may use it for creating wl_shm buffers. The compositor must be able to handle the pixel format when a client requests it. so like, don't advertise something you can't serve, that's catfishing 🐟

The compositor by default supports WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888.

🍓 int wl_display_add_socket (struct wl_display * display, const char * name)

Add a socket to Wayland display for the clients to connect.

Parameters

  • display — Wayland display to which the socket should be added.
  • name — Name of the Unix socket.

Returns

0 if success. -1 if failed.

This adds a Unix socket to the Wayland display, which can be used by clients to connect to the Wayland display.

If NULL is passed as name, then it would look for the WAYLAND_DISPLAY env variable for the socket name. If WAYLAND_DISPLAY is not set, then default wayland-0 is used.

If the socket name is a relative path, the Unix socket will be created in the directory pointed to by environment variable XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is invalid or not set, then this function fails and returns -1. 🙈

If the socket name is an absolute path, then it is used as-is for the Unix socket.

The length of the computed socket path must not exceed the maximum length of a Unix socket path. The function also fails if the user does not have write permission in the directory, or if the path is already in use.

✨ three ways to fail, three ways to cry: bad XDG_RUNTIME_DIR, no write permission, path already taken. pick your fighter.

💖 const char * wl_display_add_socket_auto (struct wl_display * display)

Automatically pick a Wayland display socket for the clients to connect to.

okay we're stopping right there because part 2 is coming and she has more to say 🫶 stay tuned bestie

Parameters

  • display — the Wayland display this socket is getting added to 🫶

Returns

The socket name if it ate (success). NULL if it flopped (failed).

This one adds a Unix socket to a Wayland display so clients can connect to it, bestie. The name gets picked automatically — it just grabs the first available name in the sequence "wayland-0", "wayland-1", "wayland-2", ..., all the way to "wayland-32". 💅

The string this function hands back is owned by the library — do not free it. Not yours, don't touch, no cap. 🙈

See also

wl_display_add_socket

int wl_display_add_socket_fd (struct wl_display * display, int sock_fd)

Add a socket with an existing fd to the Wayland display so clients can connect. It's giving "I already have the socket, I just need you to hold it". ✨

Parameters

  • display — the Wayland display to which the socket should be added.
  • sock_fd — the existing socket file descriptor to be used.

Returns

0 if success. -1 if failed.

Okay so the existing socket fd has to already be created, opened, and locked. Like, all of that. And the fd must be properly set to CLOEXEC and bound to a socket file with both bind() and listen() already called. No shortcuts, bestie. 🎀

On success, ownership of the socket fd is transferred to libwayland: libwayland will close the socket when the display is destroyed, or when wl_display_remove_socket_fd() is called. So it's not your socket anymore, it's ours. 💖

void wl_display_cancel_read (struct wl_display * display)

Cancel read intention on the display's fd. Like unsending a text but for a read. 😭

Parameters

  • display — the display context object.

After a thread successfully called wl_display_prepare_read(), it must either call wl_display_read_events() or wl_display_cancel_read(). If the threads don't follow this rule, it will lead to deadlock. And deadlock is not the vibe. 💀

See also

wl_display_prepare_read(), wl_display_read_events()

struct wl_display * wl_display_connect (const char * name)

Connect to a Wayland display. The main character moment fr fr. 👑

Parameters

  • 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 gets replaced with the WAYLAND_DISPLAY environment variable if it's set — otherwise the display "wayland-0" is used. Slay, it figures it out for you. ✨

If WAYLAND_SOCKET is set, it's interpreted as a file descriptor number referring to an already opened socket. In this case, the socket is used as-is and name is ignored. Periodt.

If name is a relative path, then the socket is opened relative to the XDG_RUNTIME_DIR directory.

If name is an absolute path, then that path is used as-is for the location of the socket at which the Wayland server is listening — no qualification inside XDG_RUNTIME_DIR is attempted. It's giving "I know exactly where I'm going". 🌈

If name is NULL and the WAYLAND_DISPLAY environment variable is set to an absolute pathname, then that pathname is used as-is for the socket in the same manner as if name held an absolute path. Support for absolute paths in name and WAYLAND_DISPLAY is present since Wayland version 1.15. ⭐

struct wl_display * wl_display_connect_to_fd (int fd)

Connect to a Wayland display on an already open fd. Reusing, we love to see it. 🫶

Parameters

  • 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. So either way, that fd is getting closed by someone — and that someone is not you. 💅

struct wl_display * wl_display_create (void )

Create a Wayland display object. Birth of an icon. 🦋

Returns

The Wayland display object. Null if failed to create.

This creates the wl_display object. That's it, that's the whole thing, and honestly? Iconic. ✨

struct wl_display * wl_display_create_queue (struct wl_display * display)

Create a new event queue for this display. A whole new queue just dropped. 🎀

Parameters

  • display — the display context object.

Returns

A new event queue associated with this display or NULL on failure.

struct wl_display * wl_display_create_queue_with_name (struct wl_display * display, const char * name)

Create a new event queue for this display and give it a name. Because unnamed queues are so last season. 💅

Parameters

  • display — the display context object.
  • name — a human readable queue name.

Returns

A new event queue associated with this display or NULL on failure.

void wl_display_destroy (struct wl_display * display)

Destroy the Wayland display object. Time to say goodbye bestie. 😭

Parameters

  • display — the Wayland display object which should be destroyed.

This function emits the wl_display destroy signal, releases all the sockets added to this display, free's all the globals associated with this display, free's memory of additional shared memory formats, and destroys the display object. It does the whole cleanup routine and it does it flawlessly. 🌸

See also

wl_display_add_destroy_listener

void wl_display_destroy_clients (struct wl_display * display)

Destroy all clients connected to the display. Mass exit, everyone out. 💀

Parameters

  • display — the display object.

This function should be called right before wl_display_destroy() to make sure all client resources are closed properly. Destroying a client from within wl_display_destroy_clients() is safe, but creating one will leak resources and raise a warning. So don't do that. Seriously. 🙈

void wl_display_disconnect (struct wl_display * display)

Close a connection to a Wayland display. We're logging off. 😌

Parameters

  • display — the display context object.

Close the connection to display. The wl_proxy and wl_event_queue objects need to be manually destroyed by the caller before disconnecting. Like, clean up your own mess first, then disconnect. Periodt. ✨

int wl_display_dispatch (struct wl_display * display)

Process incoming events. The classic. 🔥

Parameters

  • display — the display context object.

Returns

The number of dispatched events on success or -1 on failure.

Dispatch events on the default event queue.

If the default 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 default event queue are dispatched. On failure -1 is returned and errno set appropriately.

In a multi threaded environment, do not manually wait using poll() (or equivalent) before calling this function, as doing so might cause a dead lock. If external reliance on poll() (or equivalent) is required, see wl_display_prepare_read_queue() for how to do so.

This function is thread safe as long as it dispatches the right queue on the right thread. It's also compatible with the multi thread event reading preparation API (see wl_display_prepare_read_queue()), and uses the equivalent functionality internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock. No cap, it will just hang there. 💀

Note — It is not possible to check if there are events on the queue or not. For dispatching default queue events without blocking, see wl_display_dispatch_pending().

See also

wl_display_dispatch_pending(), wl_display_dispatch_queue(), wl_display_read_events()

int wl_display_dispatch_pending (struct wl_display * display)

Dispatch default queue events without reading from the display fd. Zero blocking, maximum slay. 💅

Parameters

  • 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. So polite of it. 🎀

See also

wl_display_dispatch(), wl_display_dispatch_queue(), wl_display_flush()

int wl_display_dispatch_pending_single (struct wl_display * display)

Dispatch at most one pending event in the default event queue. Just one. Little treat. 🍓

Parameters

  • display — the display context object.

Returns

The number of dispatched events (0 or 1) on success or -1 on failure.

Dispatch at most one pending event for objects assigned to the default event queue. On failure -1 is returned and errno set appropriately. If there are no events queued, this function returns immediately.

Since

1.25.0

int wl_display_dispatch_queue (struct wl_display * display, struct wl_event_queue * queue)

Dispatch events in an event queue. Pick your queue, dispatch your queue. ✨

Parameters

  • display — the display context object.
  • queue — the event queue to dispatch.

Returns

The number of dispatched events on success or -1 on failure.

Dispatch events on the given event queue.

If the given 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 given event queue are dispatched. On failure -1 is returned and errno set appropriately.

In a multi threaded environment, do not manually wait using poll() (or equivalent) before calling this function, as doing so might cause a dead lock. If external reliance on poll() (or equivalent) is required, see wl_display_prepare_read_queue() for how to do so.

This function is thread safe as long as it dispatches the right queue on the right thread. It's also compatible with the multi thread event reading preparation API (see wl_display_prepare_read_queue()), and uses the equivalent functionality internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock.

It can be used as a helper function to ease the procedure of reading and dispatching events. So convenient, honestly. 🫶

Note — Since Wayland 1.5 the display has an extra queue for its own events (i. e. delete_id). This queue is dispatched always, no matter what queue we passed as an argument to this function. That means that this function can return even when it has not dispatched any event for the given queue. Sneaky little extra queue. 💀

See also

wl_display_dispatch(), wl_display_dispatch_pending(), wl_display_dispatch_queue_pending(), wl_display_prepare_read_queue()

int wl_display_dispatch_queue_pending (struct wl_display * display, struct wl_event_queue * queue)

Dispatch pending events in an event queue. Same energy as the pending one but for your queue. 🌈

Parameters

  • 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

int wl_display_dispatch_queue_pending_single (struct wl_display * display, struct wl_event_queue * queue)

Dispatch at most one pending event in an event queue. One event, one queue, one moment. 🌸

Parameters

  • display — the display context object.
  • queue — the event queue to dispatch.

Returns

The number of dispatched events (0 or 1) on success or -1 on failure.

Dispatch at most one pending event 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.25.0

int wl_display_dispatch_queue_timeout (struct wl_display * display, struct wl_event_queue * queue, const struct timespec * timeout) 💅

Dispatch events in an event queue with a timeout — bestie, it's the same vibe as wl_display_dispatch_queue() but with a clock ticking in the background ⏰

Parameters

  • display — the display context object
  • queue — the event queue to dispatch
  • timeout — a timeout describing how long the call should block trying to dispatch events

Returns

  • The number of dispatched events on success, -1 on failure

This function behaves identical to wl_display_dispatch_queue() except that it also takes a timeout and returns 0 if the timeout elapsed. it literally returns zero when time's up, iconic ✨

Passing NULL as a timeout means an infinite timeout. An empty timespec causes wl_display_dispatch_queue_timeout() to return immediately even if no events have been dispatched. immediately immediately. no waiting. zero chill. 💀

If a timeout is passed to wl_display_dispatch_queue_timeout() it is updated to the remaining time. so peek at it after, it's telling you how much time you got left 🕰️

See also

  • wl_display_dispatch_queue()

int wl_display_flush (struct wl_display * display) 🚰

Send all buffered requests on the display to the server — it's giving "dump the whole queue, bestie" energy

Parameters

  • 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 always call this function before blocking on input from the display fd. always, bestie, not "sometimes", not "when I remember" 💖 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. no blocking, no drama, just poll and vibe 🦋

struct wl_list * wl_display_get_client_list (struct wl_display * display) 👑

Get the list of currently connected clients — the guest list, fr fr

Parameters

  • display — the display object

This function returns a pointer to the list of clients currently connected to the display. You can iterate on the list by using the wl_client_for_each macro. The returned value is valid for the lifetime of the display. You must not modify the returned list, but only access it. 👀 look, don't touch.

See also

  • wl_client_for_each()
  • wl_client_get_link()
  • wl_client_from_link()

int wl_display_get_error (struct wl_display * display) 😭

Retrieve the last error that occurred on a display — the receipts, bestie

Parameters

  • 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. like, that's it, that's the whole display, gone, periodt. 💀

int wl_display_get_fd (struct wl_display * display) 🔌

Get a display context's file descriptor — your all-access pass to the main loop

Parameters

  • 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. plug it straight into your toolkit's event loop and slay ✨

uint32_t wl_display_get_protocol_error (struct wl_display * display, const struct wl_interface ** interface, uint32_t * id) 🕵️‍♀️

Retrieves the information about a protocol error: the who, the what, the which-object

Parameters

  • display — the Wayland display
  • interface — if not NULL, stores the interface where the error occurred, or NULL, if unknown.
  • id — if not NULL, stores the object id that generated the error, or 0, if the object id is unknown. There's no guarantee the object is still valid; the client must know if it deleted the object. no cap, that object might already be gone gone 💀

Returns

  • The error code as defined in the interface specification.
int err = wl_display_get_error(display);

if (err == EPROTO) {
       code = wl_display_get_protocol_error(display, &interface, &id);
       handle_error(code, interface, id);
}

...

uint32_t wl_display_get_serial (const struct wl_display * display) 🔢

Get the current serial number — just a lil peek, no changes 👀

Parameters

  • display — the display object

This function returns the most recent serial number, but does not increment it. read-only vibes only 🎀

uint32_t wl_display_next_serial (struct wl_display * display) ⏭️

Get the next serial number — this one does bump it

Parameters

  • display — the display object

This function increments the display serial number and returns the new value. +1 and it's yours 💅

int wl_display_prepare_read (struct wl_display * display) 🛋️

Prepare to read events from the display's file descriptor — laying the groundwork, bestie

Parameters

  • display — the display context object

Returns

  • 0 on success or -1 if event queue was not empty

This function does the same thing as wl_display_prepare_read_queue() with the default queue passed as the queue.

See also

  • wl_display_prepare_read_queue

int wl_display_prepare_read_queue (struct wl_display * display, struct wl_event_queue * queue) 🧚

Prepare to read events from the display's file descriptor to a queue — the serious one, the one that keeps threads from fighting

Parameters

  • display — the display context object
  • queue — the event queue to use

Returns

  • 0 on success or -1 if event queue was not empty

This function (or wl_display_prepare_read()) must be called before reading from the file descriptor using wl_display_read_events(). Calling wl_display_prepare_read_queue() announces the calling thread's 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, and if not -1 is returned and errno set to EAGAIN. queue not empty? then nope, -1, EAGAIN, try again

If a thread successfully calls wl_display_prepare_read_queue(), it must either call wl_display_read_events() when it's ready or cancel the read intention by calling wl_display_cancel_read(). you made a promise, bestie. keep it or cancel it. no ghosting. 👻

Use this function before polling on the display fd or integrate the fd into a toolkit event loop in a race-free way. A correct usage would be (with most error checking left out):

while (wl_display_prepare_read_queue(display, queue) != 0)
        wl_display_dispatch_queue_pending(display, queue);
wl_display_flush(display);

ret = poll(fds, nfds, -1);
if (has_error(ret))
        wl_display_cancel_read(display);
else
        wl_display_read_events(display);

wl_display_dispatch_queue_pending(display, queue);

Here we call wl_display_prepare_read_queue(), 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_queue() fails, we dispatch the pending events and try again until we're successful. loop until it works, that's the whole strategy 🔁

The wl_display_prepare_read_queue() function doesn't acquire exclusive access to the display's fd. It only registers that the thread calling this function has intention to read from fd. When all registered readers call wl_display_read_events(), only one (at random) eventually reads and queues the events and the others are sleeping meanwhile. This way we avoid races and still can read from more threads. one of them gets picked, the rest nap, nobody races, everybody wins 😴✨

See also

  • wl_display_cancel_read(), wl_display_read_events(), wl_display_prepare_read()

int wl_display_read_events (struct wl_display * display) 📖

Read events from display file descriptor — the actual reading part, finally

Parameters

  • display — the display context object

Returns

  • 0 on success or -1 on error. In case of error errno will be set accordingly

Calling this function will result in data available on the display file descriptor being read and read events will be queued on their corresponding event queues.

Before calling this function, depending on what thread it is to be called from, wl_display_prepare_read_queue() or wl_display_prepare_read() needs to be called. See wl_display_prepare_read_queue() for more details. no skipping the prep step, it's not optional, it's the rules

When being called at a point where other threads have been prepared to read (using wl_display_prepare_read_queue() or wl_display_prepare_read()) this function will sleep until all other prepared threads have either been cancelled (using wl_display_cancel_read()) or them self entered this function. The last thread that calls this function will then read and queue events on their corresponding event queues, and finally wake up all other wl_display_read_events() calls causing them to return. last one in does the work and wakes everybody up. main character energy, honestly. 👑

If a thread cancels a read preparation when all other threads that have prepared to read has either called wl_display_cancel_read() or wl_display_read_events(), all reader threads will return without having read any data. everybody goes home with nothing. that's just how it is.

To dispatch events that may have been queued, call wl_display_dispatch_pending() or wl_display_dispatch_queue_pending(). queued ≠ dispatched, don't forget the second step 🎀

See also

  • wl_display_prepare_read(), wl_display_cancel_read(), wl_display_dispatch_pending(), wl_display_dispatch()

int wl_display_remove_socket_fd (struct wl_display * display, int sock_fd) 🗑️

Remove a socket fd from the Wayland display. bye bestie, uninvited

Parameters

  • display — Wayland display from which the socket should be removed.
  • sock_fd — The socket file descriptor to be removed.

Returns

  • 0 if success. -1 if failed.

Remove a socket fd previously added via wl_display_add_socket_fd(). undo button, basically ↩️

Since

  • 1.25.90

int wl_display_roundtrip (struct wl_display * display) 🔄

Block until all pending request are processed by the server — the "wait for it…" of Wayland

Parameters

  • display — the display context object

Returns

  • The number of dispatched events on success or -1 on failure

This function blocks until the server has processed all currently issued requests by sending a request to the display server and waiting for a reply before returning. it literally knocks on the server's door and waits for an answer 🚪

This function uses wl_display_dispatch_queue() internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock. DEAD LOCK. do not. I'm so serious. 💀

Note — This function may dispatch other events being received on the default queue. side quest events may appear, that's normal

int wl_display_roundtrip_queue (struct wl_display * display, struct wl_event_queue * queue) 🔁

Block until all pending request are processed by the server — same energy, but you pick the queue

Parameters

  • display — the display context object
  • queue — the queue on which to run the roundtrip

Returns

  • The number of dispatched events on success or -1 on failure

This function blocks until the server has processed all currently issued requests by sending a request to the display server and waiting for a reply before returning.

This function uses wl_display_dispatch_queue() internally. It is not allowed to call this function while the thread is being prepared for reading events, and doing so will cause a dead lock. same warning, same dead lock, same tragedy if you ignore it 😭

Note — This function may dispatch other events being received on the given queue. the queue you passed, specifically. that one.

See also

  • wl_display_roundtrip()

void wl_display_set_default_max_buffer_size (struct wl_display * display, size_t max_buffer_size) 🎀

okay so bestie, this one sets the default maximum size for connection buffers of new clients ✨

Parameters:

  • display — the display object
  • max_buffer_size — the default maximum size of the connection buffers

This function sets the default size of the internal connection buffers for new clients. It doesn't change the buffer size for existing wl_client.

The connection buffer size of an existing wl_client can be adjusted using wl_client_set_max_buffer_size().

The actual size of the connection buffers is a power of two, so the requested max_buffer_size is rounded up to the nearest power of two value. 🔢

The minimum buffer size is 4096.

See also: wl_client_set_max_buffer_size
Since: 1.22.90

void wl_display_set_global_filter (struct wl_display * display, wl_display_global_filter_func_t filter, void * data) 🦋

Set a filter function for global objects. this is like the bouncer for your globals, no cap 💅

Parameters:

  • display — The Wayland display object.
  • filter — The global filter function.
  • data — User data to be associated with the global filter.

Set a filter for the wl_display to advertise or hide global objects to clients. The set filter will be used during wl_global advertisement to determine whether a global object should be advertised to a given client, and during wl_global binding to determine whether a given client should be allowed to bind to a global.

Clients that try to bind to a global that was filtered out will have an error raised. 😱

Setting the filter NULL will result in all globals being advertised to all clients. The default is no filter.

The filter should be installed before any client connects and should always take the same decision given a client and a global. Not doing so will result in inconsistent filtering and broken wl_registry event sequences. ⚠️

void wl_display_set_max_buffer_size (struct wl_display * display, size_t max_buffer_size) 🌸

Adjust the maximum size of the client connection buffers. it's giving limit energy ✨

Parameters:

  • display — The display context object
  • max_buffer_size — The maximum size of the connection buffers

Client buffers are unbounded by default. This function sets a limit to the size of the connection buffers.

A value of 0 for max_buffer_size requests the buffers to be unbounded.

The actual size of the connection buffers is a power of two, so the requested max_buffer_size is rounded up to the nearest power of two value. 🔢

Lowering the maximum size may not take effect immediately if the current content of the buffer does not fit within the new size limit.

Since: 1.22.90

Field Documentation 🫖

here's the tea on what's inside the wl_display struct:

  • struct wl_array wl_display::additional_shm_formats
  • struct wl_list wl_display::client_list
  • struct wl_priv_signal wl_display::create_client_signal
  • struct wl_priv_signal wl_display::destroy_signal
  • wl_display_global_filter_func_t wl_display::global_filter
  • void* wl_display::global_filter_data
  • struct wl_list wl_display::global_list
  • struct wl_event_loop* wl_display::loop
  • size_t wl_display::max_buffer_size
  • uint32_t wl_display::next_global_name
  • struct wl_list wl_display::protocol_loggers
  • struct wl_list wl_display::registry_resource_list
  • bool wl_display::run
  • uint32_t wl_display::serial
  • struct wl_list wl_display::socket_list
  • struct wl_event_source* wl_display::term_source
  • int wl_display::terminate_efd

Author ✍️

Generated automatically by Doxygen for Wayland from the source code. 🤖✨

That's a wrap! This page is from Wayland version 1.26.0, and it's the wl_display(3) manual. Bye bestie! 💅✨

📦 where this page comes from