WlDisplayBase

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

A WlDisplay object represents a client connection to a Wayland compositor. It is created with either WlDisplay.connect() or WlDisplay.connect_to_fd(). A connection is terminated using disconnect().

A WlDisplay is also used as the WlProxy for the wl_display 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 WlDisplay.flush().

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

A WlDisplay has at least one event queue, called the <em>default queue</em>. Clients can create additional event queues with WlDisplay.createQueue() 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 WlDisplay.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 WlDisplay.dispatchQueue(). This function behaves exactly the same as WlDisplay.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 \em poll(2) after that it would block, even though there might be events queued on the default queue. Those events should be dispatched with WlDisplay.dispatchPending() or WlDisplay.dispatchQueuePending() before flushing and blocking.