class AttachToken

Create a new token to add a new participant to an existing logical

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

When [`fuchsia.sysmem2/BufferCollection.AttachToken`] is used, the sub

tree rooted at the attached [`fuchsia.sysmem2/BufferCollectionToken`]

goes through the normal procedure of setting constraints or closing

[`fuchsia.sysmem2/Node`](s), and then appearing to allocate buffers from

clients' point of view, despite the possibility that all the buffers

were actually allocated previously. This process is called "logical

allocation". Most instances of "allocation" in docs for other messages

can also be read as "allocation or logical allocation" while remaining

valid, but we just say "allocation" in most places for brevity/clarity

of explanation, with the details of "logical allocation" left for the

docs here on `AttachToken`.

Failure of an attached `Node` does not propagate to the parent of the

attached `Node`. More generally, failure of a child `Node` is blocked

from reaching its parent `Node` if the child is attached, or if the

child is dispensable and the failure occurred after logical allocation

(see [`fuchsia.sysmem2/BufferCollectionToken.SetDispensable`]).

A participant may in some scenarios choose to initially use a

dispensable token for a given instance of a delegate participant, and

then later if the first instance of that delegate participant fails, a

new second instance of that delegate participant my be given a token

created with `AttachToken`.

From the point of view of the [`fuchsia.sysmem2/BufferCollectionToken`]

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

[`fuchsia.sysmem2/BufferCollectionToken.Duplicate`] the token as needed,

and can send the token to a different process/participant. The

`BufferCollectionToken` `Node` should be converted to a

`BufferCollection` `Node` as normal by sending

[`fuchsia.sysmem2/Allocator.BindSharedCollection`], or can be closed

without causing subtree failure by sending

[`fuchsia.sysmem2/BufferCollectionToken.Release`]. Assuming the former,

the [`fuchsia.sysmem2/BufferCollection.SetConstraints`] message or

[`fuchsia.sysmem2/BufferCollection.Release`] message should be sent to

the `BufferCollection`.

Within the subtree, a success result from

[`fuchsia.sysmem2/BufferCollection.WaitForAllBuffersAllocated`] means

the subtree participants' constraints were satisfiable using the

already-existing buffer collection, the already-established

[`fuchsia.sysmem2/BufferCollectionInfo`] including image format

constraints, and the already-existing other participants (already added

via successful logical allocation) and their specified buffer counts in

their constraints. A failure result means the new participants'

constraints cannot be satisfied using the existing buffer collection and

its already-added participants. Creating a new collection instead may

allow all participants' 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.

Further subtrees under this subtree are considered for logical

allocation only after this subtree has completed logical allocation.

Assignment of existing buffers to participants'

[`fuchsia.sysmem2/BufferCollectionConstraints.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 [`fuchsia.sysmem2/BufferCollectionToken.SetDispensable`], which

in contrast to `AttachToken`, has the created token `Node` + child

`Node`(s) (in the created subtree but not in any subtree under this

subtree) participate in constraints aggregation along with its parent

during the parent's allocation or logical allocation.

Similar to [`fuchsia.sysmem2/BufferCollectionToken.Duplicate`], the

newly created token needs to be [`fuchsia.sysmem2/Node.Sync`]ed to

sysmem before the new token can be passed to `BindSharedCollection`. The

`Sync` of the new token can be accomplished with

[`fuchsia.sysmem2/BufferCollection.Sync`] after converting the created

`BufferCollectionToken` to a `BufferCollection`. Alternately,

[`fuchsia.sysmem2/BufferCollectionToken.Sync`] on the new token also

works. Or using [`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`]

works. As usual, 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.

All table fields are currently required.

+ request `rights_attentuation_mask` This allows attenuating the VMO

rights of the subtree. These values for `rights_attenuation_mask`

result in no attenuation (note that 0 is not on this list):

+ ZX_RIGHT_SAME_RIGHTS (preferred)

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

+ request `token_request` The server end of the `BufferCollectionToken`

channel. The client retains the client end.