3

I've been working with the Wayland protocol lately and many functions include a unit32_t serial parameter. Here's an example from wayland-client-protocol.h:

struct wl_shell_surface_listener {
    /**
     * ping client
     *
     * Ping a client to check if it is receiving events and sending
     * requests. A client is expected to reply with a pong request.
     */
    void (*ping)(void *data,
                 struct wl_shell_surface *wl_shell_surface,
                 uint32_t serial);
    // ...
}

The intent of this parameter is such that a client would respond with a pong to the display server, passing it the value of serial. The server would compare the serial it received via the pong with the serial it sent with the ping.

There are numerous other functions that include such a serial parameter. Furthermore, implementations of other functions within the API often increment the global wl_display->serial property to obtain a new serial value before doing some work. My question is, what is the rationale for this serial parameter, in a general sense? Does it have a name? For example, is this an IPC thing, or a common practice in event-driven / asynchronous programming? Is it kind of like the XCB "cookie" concept for asynchronous method calls? Is this technique found in other programs (cite examples please)?

Another example is in glut, see glutTimerFunc discussed here as a "common idiom for asynchronous invocation." I'd love to know if this idiom has a name, and where (good citations please) it's discussed as a best practice or technique in asynchronous / even-driven programming, such as continuations or "signals and slots." Or, for example, how shared resource counts are just integers, but we consider them to be "semaphores."

ybakos
  • 8,152
  • 7
  • 46
  • 74
  • Says [here](https://wayland.freedesktop.org/docs/html/ch04.html) that they're used to avoid race conditions. – Tom Zych Mar 26 '16 at 14:48
  • @TomZych Ah, _there_ it is. I had a hard time finding this in the documentation. Thank you! – ybakos Mar 26 '16 at 15:09
  • 1
    It just helps you keep track of the context when you have multiple invocations in flight. Could be an index into an array of pointers for example. – Hans Passant Mar 26 '16 at 15:56
  • "Document how serial should work" (More info): https://bugs.freedesktop.org/show_bug.cgi?id=83488 – ybakos Mar 29 '16 at 15:26

2 Answers2

1

You may find this helpful

Some actions that a Wayland client may perform require a trivial form of authentication in the form of input event serials. For example, a client which opens a popup (a context menu summoned with a right click is one kind of popup) may want to "grab" all input events server-side from the affected seat until the popup is dismissed. To prevent abuse of this feature, the server can assign serials to each input event it sends, and require the client to include one of these serials in the request.

When the server receives such a request, it looks up the input event associated with the given serial and makes a judgement call. If the event was too long ago, or for the wrong surface, or wasn't the right kind of event — for example, it could reject grabs when you wiggle the mouse, but allow them when you click — it can reject the request.

From the server's perspective, they can simply send a incrementing integer with each input event, and record the serials which are considered valid for a particular use-case for later validation. The client receives these serials from their input event handlers, and can simply pass them back right away to perform the desired action.

https://wayland-book.com/seat.html#event-serials

江口大志
  • 41
  • 3
0

As Hans Passant and Tom Zych state in the comments, the argument is distinguishes one asynchronous invocation from another.

I'm still curious about the deeper question, which is if this technique is one commonly used in asynchronous / event-driven software, and if it has a well-known name.

Community
  • 1
  • 1
ybakos
  • 8,152
  • 7
  • 46
  • 74