wl_display_destroy (3) - Linux Manuals

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

NAME

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

SYNOPSIS

#include <wayland-client.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)

uint32_t wl_display_get_serial (struct wl_display *display)

uint32_t wl_display_next_serial (struct wl_display *display)

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

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

struct wl_array * wl_display_get_additional_shm_formats (struct wl_display *display)

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 (struct wl_display *display)

int wl_display_read_events (struct wl_display *display)

int wl_display_prepare_read (struct wl_display *display)

void wl_display_cancel_read (struct wl_display *display)

int wl_display_dispatch (struct wl_display *display)

int wl_display_dispatch_pending (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)

Public Attributes

struct wl_event_loop * loop

int run

uint32_t id

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_signal destroy_signal

struct wl_array additional_shm_formats

Detailed Description

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 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, 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 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 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 pending() before flushing and blocking.

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 compositors client list. At that point, the client is initialized and ready to run, as if the client had connected to the servers 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.

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.

On failure this function sets errno accordingly and returns NULL.

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.

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 Wayland display which can be used by clients to connect to Wayland display.

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

The Unix socket will be created in the directory pointed to by environment variable XDG_RUNTIME_DIR. If XDG_RUNTIME_DIR is not set, then this function fails and returns -1.

The length of socket path, i.e., the path set in XDG_RUNTIME_DIR and the socket name, must not exceed the maxium length of a Unix socket path. The function also fails if the user do not have write permission in the XDG_RUNTIME_DIR path or if the socket name is already in use.

void wl_display_cancel_read (struct wl_display * display)

Cancel read intention on display's fd

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 do not follow this rule it will lead to deadlock.

See also:

wl_display_prepare_read(), wl_display_read_events()

struct wl_display * wl_display_connect (const char * name)

Connect to a Wayland display

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 will be replaced with the WAYLAND_DISPLAY environment variable if it is set, otherwise display 'wayland-0' will be used.

struct wl_display * wl_display_connect_to_fd (int fd)

Connect to Wayland display on an already open fd

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.

struct wl_display * wl_display_create (void)

Create Wayland display object.

Returns:

The Wayland display object. Null if failed to create

This creates the wl_display object.

void wl_display_destroy (struct wl_display * display)

Destroy Wayland display object.

Parameters:

display The Wayland display object which should be destroyed.

Returns:

None.

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 destroy the display object.

See also:

wl_display_add_destroy_listener

void wl_display_disconnect (struct wl_display * display)

Close a connection to a Wayland display

Parameters:

display The display context object

Close the connection to display and free all resources associated with it.

int wl_display_dispatch (struct wl_display * display)

Process incoming events

Parameters:

display The display context object

Returns:

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

Dispatch the display's 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.

In multi-threaded environment, programmer may want to use wl_display_read_events(). However, use of wl_display_read_events() must not be mixed with wl_display_dispatch(). See wl_display_read_events() and wl_display_prepare_read() for more details.

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

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.

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 other queues while reading all data from the display fd. When the main loop returns from the handler, 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 default 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 default queue.

See also:

wl_display_dispatch(), wl_display_dispatch_queue(), wl_display_flush()

int wl_display_flush (struct wl_display * display)

Send all buffered requests on the display to the server

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 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.

struct wl_array * wl_display_get_additional_shm_formats (struct wl_display * display)

Get list of additional wl_shm pixel formats

Parameters:

display The display object

This function returns the list of addition wl_shm pixel formats that the compositor supports. WL_SHM_FORMAT_ARGB8888 and WL_SHM_FORMAT_XRGB8888 are always supported and not included in the array, but all formats added through wl_display_add_shm_format() will be in the array.

See also:

wl_display_add_shm_format()

int wl_display_get_error (struct wl_display * display)

Retrieve the last error that occurred on a display

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.

int wl_display_get_fd (struct wl_display * display)

Get a display context's file descriptor

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.

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:

Parameters:

display The Wayland display
interface if not NULL, stores the interface where the error occurred
id if not NULL, stores the object id that generated the error. There's no guarantee the object is still valid; the client must know if it deleted the object.

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 (struct wl_display * display)

Get the current serial number

Parameters:

display The display object

This function returns the most recent serial number, but does not increment it.

uint32_t wl_display_next_serial (struct wl_display * display)

Get the next serial number

Parameters:

display The display object

This function increments the display serial number and returns the new value.

int wl_display_prepare_read (struct wl_display * display)

Prepare to read events from the display's file descriptor

Parameters:

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 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 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. A correct usage would be (we left out most of error checking):

while (wl_display_prepare_read(display) != 0)
        wl_display_dispatch_pending(display);
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_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.

When using wl_display_dispatch() we'd have something like:

wl_display_dispatch_pending(display);
wl_display_flush(display);
poll(fds, nfds, -1);
wl_display_dispatch(display);

This sequence in not thread-safe. The race is immediately after poll(), where one thread could preempt and read events before the other thread calls wl_display_dispatch(). This call now blocks and starves the other fds in the event loop.

Another race would be when using more event queues. When one thread calls wl_display_dispatch(_queue)(), then it reads all events from display's fd and queues them in appropriate queues. Then it dispatches only its own queue and the other events are sitting in their queues, waiting for dispatching. If that happens before the other thread managed to call poll(), it will block with events queued.

wl_display_prepare_read() 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.

If the relevant queue is not the default queue, then wl_display_prepare_read_queue() and wl_display_dispatch_queue_pending() need to be used instead.

See also:

wl_display_cancel_read(), wl_display_read_events()

int wl_display_read_events (struct wl_display * display)

Read events from display file descriptor

Parameters:

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 available 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. When running in more threads (which is the usual case, since we'd use wl_display_dispatch() otherwise), every thread must call wl_display_prepare_read() before calling this function.

After calling wl_display_prepare_read() there can be some extra code before calling wl_display_read_events(), for example poll() or alike. Example of code in a thread:

while (wl_display_prepare_read(display) < 0)
        wl_display_dispatch_pending(display);
wl_display_flush(display);

... some code ...

fds[0].fd = wl_display_get_fd(display);
fds[0].events = POLLIN;
poll(fds, 1, -1);

if (!everything_ok()) {
   wl_display_cancel_read(display);
   handle_error();
}

if (wl_display_read_events(display) < 0)
   handle_error();

...

After wl_display_prepare_read() succeeds, other threads that enter wl_display_read_events() will sleep until the very last thread enters it too or cancels. Therefore when the display fd becomes (or already is) readable, wl_display_read_events() should be called as soon as possible to unblock all threads. If wl_display_read_events() will not be called, then wl_display_cancel_read() must be called instead to let the other threads continue.

This function must not be called simultaneously with wl_display_dispatch(). It may lead to deadlock. If programmer wants, for some reason, use wl_display_dispatch() in one thread and wl_display_prepare_read() with wl_display_read_events() in another, extra care must be taken to serialize these calls, i. e. use mutexes or similar (on whole prepare + read sequence)

See also:

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

int wl_display_roundtrip (struct wl_display * display)

Block until all pending request are processed by the server

Parameters:

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 the default event queue.

Note:

This function uses wl_display_dispatch_queue() internally. If you are using wl_display_read_events() from more threads, don't use this function (or make sure that calling wl_display_roundtrip() doesn't interfere with calling wl_display_prepare_read() and wl_display_read_events())

Author

Generated automatically by Doxygen for Wayland from the source code.