NAME
wldisplay - Represents a connection to the compositor and acts as a proxy to the wldisplay singleton object. SYNOPSIS
#include
Public Member Functions struct wlclient * wlclientcreate (struct wldisplay *display, int fd) struct wldisplay * wldisplaycreate (void) void wldisplaydestroy (struct wldisplay *display) void wldisplaysetglobalfilter (struct wldisplay *display, wldisplayglobalfilterfunct filter, void *data) uint32t wldisplaygetserial (struct wldisplay *display) uint32t wldisplaynextserial (struct wldisplay *display) void wldisplaydestroyclients (struct wldisplay *display) int wldisplayaddsocketfd (struct wldisplay *display, int sockfd) int wldisplayaddsocket (struct wldisplay *display, const char *name) struct wlprotocollogger * wldisplayaddprotocollogger (struct wldisplay *display, wlprotocolloggerfunct func, void *userdata) uint32t * wldisplayaddshmformat (struct wldisplay *display, uint32t format) struct wllist * wldisplaygetclientlist (struct wldisplay *display) struct wleventqueue * wldisplaycreatequeue (struct wldisplay *display) struct wldisplay * wldisplayconnecttofd (int fd) struct wldisplay * wldisplayconnect (const char *name) void wldisplaydisconnect (struct wldisplay *display) int wldisplaygetfd (struct wldisplay *display) int wldisplayroundtripqueue (struct wldisplay *display, struct wleventqueue *queue) int wldisplayroundtrip (struct wldisplay *display) int wldisplayreadevents (struct wldisplay *display) int wldisplaypreparereadqueue (struct wldisplay *display, struct wleventqueue *queue) int wldisplayprepareread (struct wldisplay *display) void wldisplaycancelread (struct wldisplay *display) int wldisplaydispatchqueue (struct wldisplay *display, struct wleventqueue *queue) int wldisplaydispatchqueuepending (struct wldisplay *display, struct wleventqueue *queue) int wldisplaydispatch (struct wldisplay *display) int wldisplaydispatchpending (struct wldisplay *display) int wldisplaygeterror (struct wldisplay *display) uint32t wldisplaygetprotocolerror (struct wldisplay *display, const struct wlinterface **interface, uint32t *id) int wldisplayflush (struct wldisplay *display) Data Fields struct wleventloop * loop int run uint32t id uint32t serial struct wllist registryresourcelist struct wllist globallist struct wllist socketlist struct wllist clientlist struct wllist protocolloggers struct wlprivsignal destroysignal struct wlprivsignal createclientsignal struct wlarray additionalshmformats wldisplayglobalfilterfunct globalfilter void * globalfilterdata Detailed Description Represents a connection to the compositor and acts as a proxy to the wldisplay singleton object. A wldisplay object represents a client connection to a Wayland compositor. It is created with either wldisplayconnect() or wldisplayconnecttofd(). A connection is terminated using wldisplaydisconnect(). A wldisplay is also used as the wlproxy for the wldisplay singleton object on the compositor side. A wldisplay 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 wldisplayflush(). 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 wlproxy is called. A wldisplay has at least one event queue, called the default queue. 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 wldisplaydispatch() 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 wldisplaydispatchqueuepending() before flushing and blocking. Member Function Documentation struct wlclient * wlclientcreate (struct wldisplay *display, intfd) 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 wlclient 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 wlclient argument to the request handler will be the wlclient returned from this function. The other end of the socket can be passed to wldisplayconnecttofd() on the client side or used with the WAYLANDSOCKET environment variable on the client side. Listeners added with wldisplayaddclientcreatedlistener() will be notified by this function after the client is fully constructed. On failure this function sets errno accordingly and returns NULL. struct wlprotocollogger * wldisplayaddprotocollogger (struct wldisplay *display, wlprotocolloggerfunctfunc, void *userdata) 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 userdata 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. errno is set on error. Parameters: display The display object func The function to call to log a new protocol message userdata The user data pointer to pass to func Returns: The protol logger object on success, NULL on failure. See Also: wlprotocolloggerdestroy uint32t * wldisplayaddshmformat (struct wldisplay *display, uint32tformat) Add support for a wlshm pixel format Parameters: display The display object format The wlshm pixel format to advertise Returns: A pointer to the wlshm format that was added to the list or NULL if adding it to the list failed. Add the specified wlshm format to the list of formats the wlshm 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 wlshm buffers. The compositor must be able to handle the pixel format when a client requests it. The compositor by default supports WLSHMFORMATARGB8888 and WLSHMFORMATXRGB8888. int wldisplayaddsocket (struct wldisplay *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 WAYLANDDISPLAY env variable for the socket name. If WAYLANDDISPLAY is not set, then
default wayland-0 is used. The Unix socket will be created in the directory pointed to by environment variable XDGRUNTIMEDIR. If XDGRUNTIMEDIR is not set,
then this function fails and returns -1. The length of socket path, i.e., the path set in XDGRUNTIMEDIR and the socket name, must not exceed the maximum length of a Unix socket path. The function also fails if the user do not have write permission in the XDGRUNTIMEDIR path or if the socket name is already in use. int wldisplayaddsocketfd (struct wldisplay *display, intsockfd) Add a socket with an existing fd to Wayland display for the clients to connect. Parameters: display Wayland display to which the socket should be added. sockfd The existing socket file descriptor to be used Returns:
0 if success. -1 if failed. The existing socket fd must already be created, opened, and locked. The fd must be properly set to CLOEXEC and bound to a socket file with both bind() and listen() already called. void wldisplaycancelread (struct wldisplay *display) Cancel read intention on display's fd Parameters: display The display context object After a thread successfully called wldisplayprepareread() it must either call wldisplayreadevents() or wldisplaycancelread(). If the threads do not follow this rule it will lead to deadlock. See Also: wldisplayprepareread(), wldisplayreadevents() struct wldisplay * wldisplayconnect (const char *name) Connect to a Wayland display Parameters: name Name of the Wayland display to connect to Returns: A wldisplay object or NULL on failure Connect to the Wayland display named name. If name is NULL, its value will be replaced with the WAYLANDDISPLAY environment variable if it is
set, otherwise display 'wayland-0' will be used.
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 XDGRUNTIMEDIR is attempted. If name is NULL and the WAYLANDDISPLAY 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 WAYLANDDISPLAY is present since Wayland version 1.15. struct wldisplay * wldisplayconnecttofd (intfd) Connect to Wayland display on an already open fd Parameters: fd The fd to use for the connection Returns: A wldisplay object or NULL on failure The wldisplay 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 wldisplay * wldisplaycreate (void) Create Wayland display object. Returns: The Wayland display object. Null if failed to create This creates the wldisplay object. struct wleventqueue * wldisplaycreatequeue (struct wldisplay *display) Create a new event queue for this display Parameters: display The display context object Returns: A new event queue associated with this display or NULL on failure. void wldisplaydestroy (struct wldisplay *display) Destroy Wayland display object. Parameters: display The Wayland display object which should be destroyed. Returns: None. This function emits the wldisplay 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: wldisplayadddestroylistener void wldisplaydestroyclients (struct wldisplay *display) Destroy all clients connected to the display Parameters: display The display object This function should be called right before wldisplaydestroy() to ensure all client resources are closed properly. Destroying a client from within wldisplaydestroyclients() is safe, but creating one will leak resources and raise a warning. void wldisplaydisconnect (struct wldisplay *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 wldisplaydispatch (struct wldisplay *display) Process incoming events 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 wldisplaypreparereadqueue() of how to do so. This function is thread safe as long as it dispatches the right queue on the right thread. It is also compatible with the multi thread event reading preparation API (see wldisplaypreparereadqueue()), 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. Note: It is not possible to check if there are events on the queue or not. For dispatching default queue events without blocking, see wldisplaydispatchpending(). See Also: wldisplaydispatchpending(), wldisplaydispatchqueue(), wldisplayreadevents() int wldisplaydispatchpending (struct wldisplay *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. See Also: wldisplaydispatch(), wldisplaydispatchqueue(), wldisplayflush() int wldisplaydispatchqueue (struct wldisplay *display, struct wleventqueue *queue) Dispatch events in an event 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 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 wldisplaypreparereadqueue() of how to do so. This function is thread safe as long as it dispatches the right queue on the right thread. It is also compatible with the multi thread event reading preparation API (see wldisplaypreparereadqueue()), 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. Note: Since Wayland 1.5 the display has an extra queue for its own events (i. e. deleteid). This queue is dispatched always, no matter what queue we passed as an argument to this function. That means that
this function can return non-0 value even when it haven't dispatched any event for the given queue. See Also: wldisplaydispatch(), wldisplaydispatchpending(), wldisplaydispatchqueuepending(), wldisplaypreparereadqueue() int wldisplaydispatchqueuepending (struct wldisplay *display, struct wleventqueue *queue) Dispatch pending events in an event 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 wldisplayflush (struct wldisplay *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 always call this function before blocking on input from the display fd. On success, the number of bytes sent to the server is returned. On
failure, this function returns -1 and errno is set appropriately. wldisplayflush() 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 wllist * wldisplaygetclientlist (struct wldisplay *display) Get the list of currently connected clients 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 wlclientforeach macro. The returned value is valid for the lifetime of the display. You must not modify the returned list, but only access it. See Also: wlclientforeach() wlclientgetlink() wlclientfromlink() int wldisplaygeterror (struct wldisplay *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 wldisplaygetfd (struct wldisplay *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. uint32t wldisplaygetprotocolerror (struct wldisplay *display, const struct wlinterface **interface, uint32t *id) Retrieves the information about a protocol error: 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. Returns: The error code as defined in the interface specification. * int err = wldisplaygeterror(display); * * if (err == EPROTO) { * code = wldisplaygetprotocolerror(display, &interface, &id); * handleerror(code, interface, id); * } * * ... * uint32t wldisplaygetserial (struct wldisplay *display) Get the current serial number Parameters: display The display object This function returns the most recent serial number, but does not increment it. uint32t wldisplaynextserial (struct wldisplay *display) Get the next serial number Parameters: display The display object This function increments the display serial number and returns the new value. int wldisplayprepareread (struct wldisplay *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 does the same thing as wldisplaypreparereadqueue() with the default queue passed as the queue. See Also: wldisplaypreparereadqueue int wldisplaypreparereadqueue (struct wldisplay *display, struct wleventqueue *queue) Prepare to read events from the display's file descriptor to a queue 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 wldisplayprepareread()) must be called before reading from the file descriptor using wldisplayreadevents(). Calling wldisplaypreparereadqueue() announces the calling thread's intention to read and ensures that until the thread is ready to read and calls wldisplayreadevents(), 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. If a thread successfully calls wldisplaypreparereadqueue(), it must either call wldisplayreadevents() when it's ready or cancel the read intention by calling wldisplaycancelread(). 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 (wldisplaypreparereadqueue(display, queue) != 0) * wldisplaydispatchqueuepending(display, queue); * wldisplayflush(display); *
* ret = poll(fds, nfds, -1); * if (haserror(ret)) * wldisplaycancelread(display); * else * wldisplayreadevents(display); * * wldisplaydispatchqueuepending(display, queue); * Here we call wldisplaypreparereadqueue(), which ensures that between returning from that call and eventually calling wldisplayreadevents(), no other thread will read from the fd and queue events in our queue. If the call to wldisplaypreparereadqueue() fails, we dispatch the pending events and try again until we're successful. The wldisplaypreparereadqueue() 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 wldisplayreadevents(), 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. See Also: wldisplaycancelread(), wldisplayreadevents(), wldisplayprepareread() int wldisplayreadevents (struct wldisplay *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 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, wldisplaypreparereadqueue() or wldisplayprepareread() needs to be called. See wldisplaypreparereadqueue() for more details. When being called at a point where other threads have been prepared to read (using wldisplaypreparereadqueue() or wldisplayprepareread()) this function will sleep until all other prepared threads have either been cancelled (using wldisplaycancelread()) 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 wldisplayreadevents() calls causing them to return. If a thread cancels a read preparation when all other threads that have prepared to read has either called wldisplaycancelread() or wldisplayreadevents(), all reader threads will return without having read any data. To dispatch events that may have been queued, call wldisplaydispatchpending() or wldisplaydispatchqueuepending(). See Also: wldisplayprepareread(), wldisplaycancelread(), wldisplaydispatchpending(), wldisplaydispatch() int wldisplayroundtrip (struct wldisplay *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 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 wldisplaydispatchqueue() 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. Note: This function may dispatch other events being received on the default queue. int wldisplayroundtripqueue (struct wldisplay *display, struct wleventqueue *queue) Block until all pending request are processed by the server 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 wldisplaydispatchqueue() 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. Note: This function may dispatch other events being received on the given queue. See Also: wldisplayroundtrip() void wldisplaysetglobalfilter (struct wldisplay *display, wldisplayglobalfilterfunctfilter, void *data) Set a filter function for global objects Parameters: display The Wayland display object. filter The global filter funtion. data User data to be associated with the global filter. Returns: None. Set a filter for the wldisplay to advertise or hide global objects to clients. The set filter will be used during wlglobal advertisment to determine whether a global object should be advertised to a given client, and during wlglobal 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. Field Documentation struct wlarray wldisplay::additionalshmformats struct wllist wldisplay::clientlist struct wlprivsignal wldisplay::createclientsignal struct wlprivsignal wldisplay::destroysignal wldisplayglobalfilterfunct wldisplay::globalfilter void* wldisplay::globalfilterdata struct wllist wldisplay::globallist uint32t wldisplay::id struct wleventloop* wldisplay::loop struct wllist wldisplay::protocolloggers struct wllist wldisplay::registryresourcelist int wldisplay::run uint32t wldisplay::serial struct wllist wldisplay::socketlist Author Generated automatically by Doxygen for Wayland from the source code. Version 1.15.0 Tue Oct 30 2018 wldisplay(3)