Search code examples
cwayland

What's the purpose of the serial parameter in the Wayland API?


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


Solution

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