Clarify if request/event carry an immediate response or not
A few days ago I asked on the IRC why the wl_callback.done event from a wl_display.sync request was returned earlier than the xdg_surface.configure event from an initial wl_surface.commit request, even though the commit request was sent first.
From talking to kennylivensen it seems that some events are sent immediately and some are only scheduled for later. For example the wl_registry.global events must be sent immediate which means that if you call wl_display.sync after binding to the registry then the resulting wl_callback.done event must sent by the compositor after all the initial wl_registry.global events.
The spec does not state which responses must be sent immediately such that the done event from a subsequent sync request is sent afterwards, or which events are only scheduled for the future, and thus are sent out of order from a sync request.
wl_display.sync
The sync request asks the server to emit the 'done' event on the returned wl_callback object. Since requests are handled in-order and events are delivered in-order, this can be used as a barrier to ensure all previous requests and the resulting events have been handled.
wl_registry
When a client creates a registry object, the registry object will emit a global event for each global currently in the registry. Globals come and go as a result of device or monitor hotplugs, reconfiguration or other events, and the registry will send out global and global_remove events to keep the client up to date with the changes. To mark the end of the initial burst of events, the client can use the wl_display.sync request immediately after calling wl_display.get_registry.
xdg_surface
After creating a role-specific object and setting it up, the client must perform an initial commit without any buffer attached. The compositor will reply with an xdg_surface.configure event. The client must acknowledge it and is then allowed to attach a buffer to map the surface.
There is nothing in these descriptions that would suggest that wl_registry.global events are sent immediately, and that xdg_surface.configure isn't. The mention of wl_display.sync for wl_registry is only a suggestion but from reading the rest one would think that the same logic applies to xdg_surface.
I'm opening this issue to discuss what appropriate wording changes are needed to clarify this behavior.
There are certain words and phrases that are ambiguous:
- Handled in-order: With respect to what? The order the client sends them to the server?
- Delivered in-order: Again with respect to what? The requests that carry a reply, or to the order they are read from the fd? Also what does deliver mean here? Does it mean the client has called the event handler for that event?
- Emit/Send: Are these synonyms? And send when?
I'm proposing the use of new words that carry strict definitions: Some of these words are already used in the spec.
- Response/Reply: Both mean the same thing. An event that is required to be sent after a request from the client, or visa versa.
- Schedule: The client/server will respond sometime in the future, and therefore the response will be out of order with respect to the order the client/server sent requests/events that carry a response.
- Immediately: The client/server will respond immediately upon receiving the request. This means that a call to wl_display.sync immediately following a request that carries an immediate reply ensures that the wl_callback.done event is sent by the compositor afterwards.
These words must be used in the descriptions of every request/event that carries a response.
See also: