class AttachLifetimeTracking

AttachLifetimeTracking:

AttachLifetimeTracking() is intended to allow a client to wait until an

old logical buffer collection is fully or mostly deallocated before

attempting allocation of a new logical buffer collection.

Attach an eventpair endpoint to the logical buffer collection, so that

the server_end will be closed when the number of buffers allocated

drops to 'buffers_remaining'. The server_end won't close until after

logical allocation has completed.

If logical allocation fails, such as for an attached sub-tree (using

AttachToken()), the server_end will close during that failure regardless

of the number of buffers potenitally allocated in the overall logical

buffer collection.

The lifetime signalled by this event includes asynchronous cleanup of

allocated buffers, and this asynchronous cleanup cannot occur until all

holders of VMO handles to the buffers have closed those VMO handles.

Therefore clients should take care not to become blocked forever waiting

for ZX_EVENTPAIR_PEER_CLOSED to be signalled, especially if any of the

participants using the logical buffer collection are less trusted or

less reliable.

The buffers_remaining parameter allows waiting for all but

buffers_remaining buffers to be fully deallocated. This can be useful

in situations where a known number of buffers are intentionally not

closed so that the data can continue to be used, such as for keeping the

last available video picture displayed in the UI even if the video

stream was using protected output buffers. It's outside the scope of

the BufferCollection interface (at least for now) to determine how many

buffers may be held without closing, but it'll typically be in the range

0-2.

This mechanism is meant to be compatible with other protocols providing

a similar AttachLifetimeTracking() mechanism, in that duplicates of the

same event can be sent to more than one AttachLifetimeTracking(), and

the ZX_EVENTPAIR_PEER_CLOSED will be signalled when all the lifetime

over conditions are met (all holders of duplicates have closed their

handle(s)).

There is no way to cancel an attach. Closing the client end of the

eventpair doesn't subtract from the number of pending attach(es).

Closing the client's end doesn't result in any action by the server.

If the server listens to events from the client end at all, it is for

debug logging only.

The server intentionally doesn't "trust" any bits signalled by the

client. This mechanism intentionally uses only ZX_EVENTPAIR_PEER_CLOSED

which can't be triggered early, and is only triggered when all handles

to server_end are closed. No meaning is associated with any of the

other signal bits, and clients should functionally ignore any other

signal bits on either end of the eventpair or its peer.

The server_end may lack ZX_RIGHT_SIGNAL or ZX_RIGHT_SIGNAL_PEER, but

must have ZX_RIGHT_DUPLICATE (and must have ZX_RIGHT_TRANSFER to

transfer without causing CodecFactory channel failure).