Questions about object ID lifetimes

[jleivent]

Forgive the long post.  Tl;dr: what are the rules of object ID lifetime
and reuse in the Wayland protocol?

I am attempting to understand the rules of object ID lifetime within
the Wayland protocol in order to construct Wayland middleware (similar
to some of the tools featured on
https://wayland.freedesktop.org/extras.html).  I could not find a
comprehensive discussion of the details online.  If one exists, I would
greatly appreciate a link!

Middleware tools that wish to decode Wayland messages sent between the
compositor and its clients need to maintain an accurate mapping between
object ID and object interface (type).  This is needed because the wire
protocol's message header includes only the target object ID and an
opcode that is relative to the object's type (the message header also
includes the message length - about which I also have questions - to be
pursued later...).  The message (request or event) and its argument
encoding can only be determined if the object ID -> type and type +
opcode -> message mappings are accurately maintained.  The type +
opcode -> message mapping is static and can be extracted offline from
the protocol XML files.

Since object IDs can be reused, it is important for the middleware to
understand when an ID can be reused and when it cannot be to avoid
errors in the ID -> type mapping.

Because the Wayland protocol is asynchronous, any message that implies
destruction of an object should be acknowledged by the receiver before
the destructed object's ID is reused.

Fortunately, certain events and requests have been tagged as
destructors in the protocol descriptions!

Also fortunately, it appears (based on reading the wl_resource_destroy
code in wayland-server.c) that for many object IDs, specifically for
IDs of objects created by a client request (the ID appears as a new ID
arg of a request, and is thus in the client side of the ID range) and
for which the client makes a destructor request, the compositor will
always send a wl_display::delete_id event (assuming the
display_resource still exists for the client, which apparently would
only not be the case after the client connection is severed) to
acknowledge the destructor request. Any attempt to reuse that ID prior
to the wl_display::delete_id event can lead to confusion, and should be
avoided.  Reuse of the ID after the wl_display::delete_id event should
not result in any confusion.

[BTW: for the purpose of this discussion, an object is "created" when
it is introduced into a protocol message for the first time via a new_id
argument.  It does not refer to the actual allocation of the object in
memory or to its initialization.]

However, the other cases are not as easy to identify.

The other cases are:
1. an object created by a client request that has destructor events
2. an object created by the compositor

It might be true that case 1 does not exist.  Is there a general rule
against that such cases would never be considered in future expansions
of the Wayland protocol?

For objects created by the compositor, there are 2 subcases:

2a. objects with only destructor events
2b. objects with destructor requests

Again, it might be the case that 2b does not exist, as it is analogous
to case 1 above.  But, is there a general rule against such
future cases as well?  Combining 1 and 2b, is there a general rule that
says that only the object creator can initiate an object's destruction
(unprovoked by the other side of the protocol)?

For object IDs created by the compositor and with only destructor
events (case 2a), it may be necessary to understand the details of each
interface in question to decide when the ID can be reused, as there is
no universal destructor acknowledgement request comparable to the
wl_display::delete_id event.  A requirement to understand the details
to that level would make middleware development more difficult.  Insert
extreme sadness emoji here.

Thankfully, it seems that destructor events are themselves
acknowledgements of requests for destruction by the client (such as
wp_drm_lease_device_v1::released event destructor vs.
wp_drm_lease_device_v1::release request), or involve objects with a
very limited lifetime and usage, such as callbacks
(wp_presentation_feedback, zwp_linux_buffer_release, and
zwp_fullscreen_shell_mode_feedback_v1).  These limited lifetime/usage
objects are created with the knowledge that all messages for them are
destructor events, and that they are not involved in any other messages
(as targets or arguments).  Hence their destruction needs no further
acknowledgement because the request for destruction was implied by
their creation.  The destructor event is the acknowledgement of that
request.

Is this a general rule: that a destructor event is is always the
acknowledgement of a (perhaps implied) destruction request?

So there may be two general simple rules that the middleware can follow
to maintain a proper ID -> type mapping through ID reuse cycles:

1. reuse of ID is allowed after wl_display::delete_id(ID)
   "wl_display::delete_id events are the acknowledgements for all
   destruction requests"

2. reuse of ID is allowed after a destructor event targeted to ID
   "destruction events do not need acknowledgements"

But this only works if the Wayland protocol has these general
requirements:

A. Ownership vs. destruction: An object created by a client can only
have destructor requests, and an object created by the compositor can
only have destructor events.

B. All destructor requests are followed by wl_display::delete_id events
as acknowledgements

C. All destructor events are themselves acknowledgements of (implicit)
destruction requests.

D. No object can be the target or argument of a message issued by one
side after that side has issued a destructor request (explicit or
implicit).

Is this correct?  Are these actual requirements that are enforced
for the current protocol and future expansions?

Can there be cases of objects created by the compositor, where the
compositor proposes their destruction without any prior (implicit or
explicit) request to do so from the client?  If so, how are these
acknowledged?  Not allowing any such cases seems very strict.  But, if
some universal acknowledgement analog to wl_display::delete_id were to
be introduced to allow these cases, and if the events to be interpreted
as proposing destruction were tagged in the protocol as "destructors",
that would break rule 2 above.

BTW: some of the middleware tools on
https://wayland.freedesktop.org/extras.html do not follow these rules.