class AttachToken

Create a new token, for trying to add a new participant to an existing

collection, if the existing collection's buffer counts, constraints,

and participants allow.

This can be useful in replacing a failed participant, and/or in

adding/re-adding a participant after buffers have already been

allocated.

Failure of an attached token / collection does not propagate to the

parent of the attached token. Failure does propagate from a normal

child of a dispensable token to the dispensable token. Failure

of a child is blocked from reaching its parent if the child is attached,

or if the child is dispensable and the failure occurred after logical

allocation.

An initiator may in some scenarios choose to initially use a dispensable

token for a given instance of a participant, and then later if the first

instance of that participant fails, a new second instance of that

participant my be given a token created with AttachToken().

From the point of view of the client end of the BufferCollectionToken

channel, the token acts like any other token. The client can

Duplicate() the token as needed, and can send the token to a different

process. The token should be converted to a BufferCollection channel

as normal by calling BindSharedCollection(). SetConstraints() should

be called on that BufferCollection channel.

A success result from WaitForBuffersAllocated() means the new

participant's constraints were satisfiable using the already-existing

buffer collection, the already-established BufferCollectionInfo

including image format constraints, and the already-existing other

participants and their buffer counts. A failure result means the new

participant's constraints cannot be satisfied using the existing

buffer collection and its already-logically-allocated participants.

Creating a new collection instead may allow all participant's

constraints to be satisfied, assuming SetDispensable() is used in place

of AttachToken(), or a normal token is used.

A token created with AttachToken() performs constraints aggregation with

all constraints currently in effect on the buffer collection, plus the

attached token under consideration plus child tokens under the attached

token which are not themselves an attached token or under such a token.

Allocation of buffer_count to min_buffer_count_for_camping etc is

first-come first-served, but a child can't logically allocate before

all its parents have sent SetConstraints().

See also SetDispensable(), which in contrast to AttachToken(), has the

created token + children participate in constraints aggregation along

with its parent.

The newly created token needs to be Sync()ed to sysmem before the new

token can be passed to BindSharedCollection(). The Sync() of the new

token can be accomplished with BufferCollection.Sync() on this

BufferCollection. Alternately BufferCollectionToken.Sync() on the new

token also works. A BufferCollectionToken.Sync() can be started after

any BufferCollectionToken.Duplicate() messages have been sent via the

newly created token, to also sync those additional tokens to sysmem

using a single round-trip.

These values for rights_attenuation_mask result in no attenuation (note

that 0 is not on this list; 0 will output an ERROR to the system log

to help diagnose the bug in client code):

* ZX_RIGHT_SAME_RIGHTS (preferred)

* 0xFFFFFFFF (this is reasonable when an attenuation mask is computed)