class BufferCollectionToken

Ensure that previous messages have been received server side. This is

particularly useful after previous messages that created new tokens,

because a token must be known to the sysmem server before sending the

token to another participant.

Calling [`fuchsia.sysmem2/BufferCollectionToken.Sync`] on a token that

isn't/wasn't a valid token risks the `Sync` stalling forever. See

[`fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken`] for one way

to mitigate the possibility of a hostile/fake

[`fuchsia.sysmem2/BufferCollectionToken`] at the cost of one round trip.

Another way is to pass the token to

[`fuchsia.sysmem2/Allocator/BindSharedCollection`], which also validates

the token as part of exchanging it for a

[`fuchsia.sysmem2/BufferCollection`] channel, and

[`fuchsia.sysmem2/BufferCollection.Sync`] can then be used without risk

of stalling.

After creating one or more [`fuchsia.sysmem2/BufferCollectionToken`](s)

and then starting and completing a `Sync`, it's then safe to send the

`BufferCollectionToken` client ends to other participants knowing the

server will recognize the tokens when they're sent by the other

participants to sysmem in a

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] message. This is an

efficient way to create tokens while avoiding unnecessary round trips.

Other options include waiting for each

[`fuchsia.sysmem2/BufferCollectionToken.Duplicate`] to complete

individually (using separate call to `Sync` after each), or calling

[`fuchsia.sysmem2/BufferCollection.Sync`] after a token has been

converted to a `BufferCollection` via

[`fuchsia.sysmem2/Allocator.BindSharedCollection`], or using

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] which includes

the sync step and can create multiple tokens at once.

###### On a [`fuchsia.sysmem2/BufferCollectionToken`] channel:

Normally a participant will convert a `BufferCollectionToken` into a

[`fuchsia.sysmem2/BufferCollection`], but a participant can instead send

`Release` via the token (and then close the channel immediately or

shortly later in response to server closing the server end), which

avoids causing buffer collection failure. Without a prior `Release`,

closing the `BufferCollectionToken` client end will cause buffer

collection failure.

###### On a [`fuchsia.sysmem2/BufferCollection`] channel:

By default the server handles unexpected closure of a

[`fuchsia.sysmem2/BufferCollection`] client end (without `Release`

first) by failing the buffer collection. Partly this is to expedite

closing VMO handles to reclaim memory when any participant fails. If a

participant would like to cleanly close a `BufferCollection` without

causing buffer collection failure, the participant can send `Release`

before closing the `BufferCollection` client end. The `Release` can

occur before or after `SetConstraints`. If before `SetConstraints`, the

buffer collection won't require constraints from this node in order to

allocate. If after `SetConstraints`, the constraints are retained and

aggregated, despite the lack of `BufferCollection` connection at the

time of constraints aggregation.

###### On a [`fuchsia.sysmem2/BufferCollectionTokenGroup`] channel:

By default, unexpected closure of a `BufferCollectionTokenGroup` client

end (without `Release` first) will trigger failure of the buffer

collection. To close a `BufferCollectionTokenGroup` channel without

failing the buffer collection, ensure that AllChildrenPresent() has been

sent, and send `Release` before closing the `BufferCollectionTokenGroup`

client end.

If `Release` occurs before

[`fuchsia.sysmem2/BufferCollectionTokenGroup.AllChildrenPresent], the

buffer collection will fail (triggered by reception of `Release` without

prior `AllChildrenPresent`). This is intentionally not analogous to how

[`fuchsia.sysmem2/BufferCollection.Release`] without

[`fuchsia.sysmem2/BufferCollection.SetConstraints`] first doesn't cause

buffer collection failure. For a `BufferCollectionTokenGroup`, clean

close requires `AllChildrenPresent` (if not already sent), then

`Release`, then close client end.

If `Release` occurs after `AllChildrenPresent`, the children and all

their constraints remain intact (just as they would if the

`BufferCollectionTokenGroup` channel had remained open), and the client

end close doesn't trigger buffer collection failure.

###### On all [`fuchsia.sysmem2/Node`] channels (any of the above):

For brevity, the per-channel-protocol paragraphs above ignore the

separate failure domain created by

[`fuchsia.sysmem2/BufferCollectionToken.SetDispensable`] or

[`fuchsia.sysmem2/BufferCollection.AttachToken`]. When a client end

unexpectedly closes (without `Release` first) and that client end is

under a failure domain, instead of failing the whole buffer collection,

the failure domain is failed, but the buffer collection itself is

isolated from failure of the failure domain. Such failure domains can be

nested, in which case only the inner-most failure domain in which the

`Node` resides fails.

Set a name for VMOs in this buffer collection.

If the name doesn't fit in ZX_MAX_NAME_LEN, the name of the vmo itself

will be truncated to fit. The name of the vmo will be suffixed with the

buffer index within the collection (if the suffix fits within

ZX_MAX_NAME_LEN). The name specified here (without truncation) will be

listed in the inspect data.

The name only affects VMOs allocated after the name is set; this call

does not rename existing VMOs. If multiple clients set different names

then the larger priority value will win. Setting a new name with the

same priority as a prior name doesn't change the name.

All table fields are currently required.

+ request `priority` The name is only set if this is the first `SetName`

or if `priority` is greater than any previous `priority` value in

prior `SetName` calls across all `Node`(s) of this buffer collection.

+ request `name` The name for VMOs created under this buffer collection.

Set information about the current client that can be used by sysmem to

help diagnose leaking memory and allocation stalls waiting for a

participant to send [`fuchsia.sysmem2/BufferCollection.SetConstraints`].

This sets the debug client info on this [`fuchsia.sysmem2/Node`] and all

`Node`(s) derived from this `Node`, unless overriden by

[`fuchsia.sysmem2/Allocator.SetDebugClientInfo`] or a later

[`fuchsia.sysmem2/Node.SetDebugClientInfo`].

Sending [`fuchsia.sysmem2/Allocator.SetDebugClientInfo`] once per

`Allocator` is the most efficient way to ensure that all

[`fuchsia.sysmem2/Node`](s) will have at least some debug client info

set, and is also more efficient than separately sending the same debug

client info via [`fuchsia.sysmem2/Node.SetDebugClientInfo`] for each

created [`fuchsia.sysmem2/Node`].

Also used when verbose logging is enabled (see `SetVerboseLogging`) to

indicate which client is closing their channel first, leading to subtree

failure (which can be normal if the purpose of the subtree is over, but

if happening earlier than expected, the client-channel-specific name can

help diagnose where the failure is first coming from, from sysmem's

point of view).

All table fields are currently required.

+ request `name` This can be an arbitrary string, but the current

process name (see `fsl::GetCurrentProcessName`) is a good default.

+ request `id` This can be an arbitrary id, but the current process ID

(see `fsl::GetCurrentProcessKoid`) is a good default.

Sysmem logs a warning if sysmem hasn't seen

[`fuchsia.sysmem2/BufferCollection.SetConstraints`] from all clients

within 5 seconds after creation of a new collection.

Clients can call this method to change when the log is printed. If

multiple client set the deadline, it's unspecified which deadline will

take effect.

In most cases the default works well.

All table fields are currently required.

+ request `deadline` The time at which sysmem will start trying to log

the warning, unless all constraints are with sysmem by then.

This enables verbose logging for the buffer collection.

Verbose logging includes constraints set via

[`fuchsia.sysmem2/BufferCollection.SetConstraints`] from each client

along with info set via [`fuchsia.sysmem2/Node.SetDebugClientInfo`] (or

[`fuchsia.sysmem2/Allocator.SetDebugClientInfo`]) and the structure of

the tree of `Node`(s).

Normally sysmem prints only a single line complaint when aggregation

fails, with just the specific detailed reason that aggregation failed,

with little surrounding context. While this is often enough to diagnose

a problem if only a small change was made and everything was working

before the small change, it's often not particularly helpful for getting

a new buffer collection to work for the first time. Especially with

more complex trees of nodes, involving things like

[`fuchsia.sysmem2/BufferCollection.AttachToken`],

[`fuchsia.sysmem2/BufferCollectionToken.SetDispensable`],

[`fuchsia.sysmem2/BufferCollectionTokenGroup`] nodes, and associated

subtrees of nodes, verbose logging may help in diagnosing what the tree

looks like and why it's failing a logical allocation, or why a tree or

subtree is failing sooner than expected.

The intent of the extra logging is to be acceptable from a performance

point of view, under the assumption that verbose logging is only enabled

on a low number of buffer collections. If we're not tracking down a bug,

we shouldn't send this message.

This gets a handle that can be used as a parameter to

[`fuchsia.sysmem2/Node.IsAlternateFor`] called on any

[`fuchsia.sysmem2/Node`]. This handle is only for use as proof that the

client obtained this handle from this `Node`.

Because this is a get not a set, no [`fuchsia.sysmem2/Node.Sync`] is

needed between the `GetNodeRef` and the call to `IsAlternateFor`,

despite the two calls typically being on different channels.

See also [`fuchsia.sysmem2/Node.IsAlternateFor`].

All table fields are currently required.

- response `node_ref` This handle can be sent via `IsAlternateFor` on a

different `Node` channel, to prove that the client obtained the handle

from this `Node`.

Check whether the calling [`fuchsia.sysmem2/Node`] is in a subtree

rooted at a different child token of a common parent

[`fuchsia.sysmem2/BufferCollectionTokenGroup`], in relation to the

passed-in `node_ref`.

This call is for assisting with admission control de-duplication, and

with debugging.

The `node_ref` must be obtained using

[`fuchsia.sysmem2/Node.GetNodeRef`].

The `node_ref` can be a duplicated handle; it's not necessary to call

`GetNodeRef` for every call to [`fuchsia.sysmem2/Node.IsAlternateFor`].

If a calling token may not actually be a valid token at all due to a

potentially hostile/untrusted provider of the token, call

[`fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken`] first

instead of potentially getting stuck indefinitely if `IsAlternateFor`

never responds due to a calling token not being a real token (not really

talking to sysmem). Another option is to call

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] with this token first

which also validates the token along with converting it to a

[`fuchsia.sysmem2/BufferCollection`], then call `IsAlternateFor`.

All table fields are currently required.

- response `is_alternate`

- true: The first parent node in common between the calling node and

the `node_ref` `Node` is a `BufferCollectionTokenGroup`. This means

that the calling `Node` and the `node_ref` `Node` will not have both

their constraints apply - rather sysmem will choose one or the other

of the constraints - never both. This is because only one child of

a `BufferCollectionTokenGroup` is selected during logical

allocation, with only that one child's subtree contributing to

constraints aggregation.

- false: The first parent node in common between the calling `Node`

and the `node_ref` `Node` is not a `BufferCollectionTokenGroup`.

Currently, this means the first parent node in common is a

`BufferCollectionToken` or `BufferCollection` (regardless of not

`Release`ed). This means that the calling `Node` and the `node_ref`

`Node` may have both their constraints apply during constraints

aggregation of the logical allocation, if both `Node`(s) are

selected by any parent `BufferCollectionTokenGroup`(s) involved. In

this case, there is no `BufferCollectionTokenGroup` that will

directly prevent the two `Node`(s) from both being selected and

their constraints both aggregated, but even when false, one or both

`Node`(s) may still be eliminated from consideration if one or both

`Node`(s) has a direct or indirect parent

`BufferCollectionTokenGroup` which selects a child subtree other

than the subtree containing the calling `Node` or `node_ref` `Node`.

* error `[fuchsia.sysmem2/Error.NOT_FOUND]` The node_ref wasn't

associated with the same buffer collection as the calling `Node`.

Another reason for this error is if the `node_ref` is an

[`zx.Handle.EVENT`] handle with sufficient rights, but isn't actually

a real `node_ref` obtained from `GetNodeRef`.

* error `[fuchsia.sysmem2/Error.PROTOCOL_DEVIATION]` The caller passed a

`node_ref` that isn't a [`zx.Handle:EVENT`] handle , or doesn't have

the needed rights expected on a real `node_ref`.

* No other failing status codes are returned by this call. However,

sysmem may add additional codes in future, so the client should have

sensible default handling for any failing status code.

Get the buffer collection ID. This ID is also available from

[`fuchsia.sysmem2/Allocator.GetVmoInfo`] (along with the `buffer_index`

within the collection).

This call is mainly useful in situations where we can't convey a

[`fuchsia.sysmem2/BufferCollectionToken`] or

[`fuchsia.sysmem2/BufferCollection`] directly, but can only convey a VMO

handle, which can be joined back up with a `BufferCollection` client end

that was created via a different path. Prefer to convey a

`BufferCollectionToken` or `BufferCollection` directly when feasible.

Trusting a `buffer_collection_id` value from a source other than sysmem

is analogous to trusting a koid value from a source other than zircon.

Both should be avoided unless really necessary, and both require

caution. In some situations it may be reasonable to refer to a

pre-established `BufferCollection` by `buffer_collection_id` via a

protocol for efficiency reasons, but an incoming value purporting to be

a `buffer_collection_id` is not sufficient alone to justify granting the

sender of the `buffer_collection_id` any capability. The sender must

first prove to a receiver that the sender has/had a VMO or has/had a

`BufferCollectionToken` to the same collection by sending a handle that

sysmem confirms is a valid sysmem handle and which sysmem maps to the

`buffer_collection_id` value. The receiver should take care to avoid

assuming that a sender had a `BufferCollectionToken` in cases where the

sender has only proven that the sender had a VMO.

- response `buffer_collection_id` This ID is unique per buffer

collection per boot. Each buffer is uniquely identified by the

`buffer_collection_id` and `buffer_index` together.

Sets the current [`fuchsia.sysmem2/Node`] and all child `Node`(s)

created after this message to weak, which means that a client's `Node`

client end (or a child created after this message) is not alone

sufficient to keep allocated VMOs alive.

All VMOs obtained from weak `Node`(s) are weak sysmem VMOs. See also

`close_weak_asap`.

This message is only permitted before the `Node` becomes ready for

allocation (else the server closes the channel with `ZX_ERR_BAD_STATE`):

* `BufferCollectionToken`: any time

* `BufferCollection`: before `SetConstraints`

* `BufferCollectionTokenGroup`: before `AllChildrenPresent`

Currently, no conversion from strong `Node` to weak `Node` after ready

for allocation is provided, but a client can simulate that by creating

an additional `Node` before allocation and setting that additional

`Node` to weak, and then potentially at some point later sending

`Release` and closing the client end of the client's strong `Node`, but

keeping the client's weak `Node`.

Zero strong `Node`(s) and zero strong VMO handles will result in buffer

collection failure (all `Node` client end(s) will see

`ZX_CHANNEL_PEER_CLOSED` and all `close_weak_asap` `client_end`(s) will

see `ZX_EVENTPAIR_PEER_CLOSED`), but sysmem (intentionally) won't notice

this situation until all `Node`(s) are ready for allocation. For initial

allocation to succeed, at least one strong `Node` is required to exist

at allocation time, but after that client receives VMO handles, that

client can `BufferCollection.Release` and close the client end without

causing this type of failure.

This implies [`fuchsia.sysmem2/Node.SetWeakOk`] as well, but does not

imply `SetWeakOk` with `for_children_also` true, which can be sent

separately as appropriate.

This indicates to sysmem that the client is prepared to pay attention to

`close_weak_asap`.

If sent, this message must be before

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

All participants using a weak [`fuchsia.sysmem2/BufferCollection`] must

send this message before `WaitForAllBuffersAllocated`, or a parent

`Node` must have sent [`fuchsia.sysmem2/Node.SetWeakOk`] with

`for_child_nodes_also` true, else the `WaitForAllBuffersAllocated` will

trigger buffer collection failure.

This message is necessary because weak sysmem VMOs have not always been

a thing, so older clients are not aware of the need to pay attention to

`close_weak_asap` `ZX_EVENTPAIR_PEER_CLOSED` and close all remaining

sysmem weak VMO handles asap. By having this message and requiring

participants to indicate their acceptance of this aspect of the overall

protocol, we avoid situations where an older client is delivered a weak

VMO without any way for sysmem to get that VMO to close quickly later

(and on a per-buffer basis).

A participant that doesn't handle `close_weak_asap` and also doesn't

retrieve any VMO handles via `WaitForAllBuffersAllocated` doesn't need

to send `SetWeakOk` (and doesn't need to have a parent `Node` send

`SetWeakOk` with `for_child_nodes_also` true either). However, if that

same participant has a child/delegate which does retrieve VMOs, that

child/delegate will need to send `SetWeakOk` before

`WaitForAllBuffersAllocated`.

+ request `for_child_nodes_also` If present and true, this means direct

child nodes of this node created after this message plus all

descendants of those nodes will behave as if `SetWeakOk` was sent on

those nodes. Any child node of this node that was created before this

message is not included. This setting is "sticky" in the sense that a

subsequent `SetWeakOk` without this bool set to true does not reset

the server-side bool. If this creates a problem for a participant, a

workaround is to `SetWeakOk` with `for_child_nodes_also` true on child

tokens instead, as appropriate. A participant should only set

`for_child_nodes_also` true if the participant can really promise to

obey `close_weak_asap` both for its own weak VMO handles, and for all

weak VMO handles held by participants holding the corresponding child

`Node`(s). When `for_child_nodes_also` is set, descendent `Node`(s)

which are using sysmem(1) can be weak, despite the clients of those

sysmem1 `Node`(s) not having any direct way to `SetWeakOk` or any

direct way to find out about `close_weak_asap`. This only applies to

descendents of this `Node` which are using sysmem(1), not to this

`Node` when converted directly from a sysmem2 token to a sysmem(1)

token, which will fail allocation unless an ancestor of this `Node`

specified `for_child_nodes_also` true.

The server_end will be closed after this `Node` and any child nodes have

have released their buffer counts, making those counts available for

reservation by a different `Node` via

[`fuchsia.sysmem2/BufferCollection.AttachToken`].

The `Node` buffer counts may not be released until the entire tree of

`Node`(s) is closed or failed, because

[`fuchsia.sysmem2/BufferCollection.Release`] followed by channel close

does not immediately un-reserve the `Node` buffer counts. Instead, the

`Node` buffer counts remain reserved until the orphaned node is later

cleaned up.

If the `Node` exceeds a fairly large number of attached eventpair server

ends, a log message will indicate this and the `Node` (and the

appropriate) sub-tree will fail.

The `server_end` will remain open when

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] converts a

[`fuchsia.sysmem2/BufferCollectionToken`] into a

[`fuchsia.sysmem2/BufferCollection`].

This message can also be used with a

[`fuchsia.sysmem2/BufferCollectionTokenGroup`].

Create additional [`fuchsia.sysmem2/BufferCollectionToken`](s) from this

one, referring to the same buffer collection.

The created tokens are children of this token in the

[`fuchsia.sysmem2/Node`] heirarchy.

This method can be used to add more participants, by transferring the

newly created tokens to additional participants.

A new token will be returned for each entry in the

`rights_attenuation_masks` array.

If the called token may not actually be a valid token due to a

potentially hostile/untrusted provider of the token, consider using

[`fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken`] first

instead of potentially getting stuck indefinitely if

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] never responds

due to the calling token not being a real token.

In contrast to [`fuchsia.sysmem2/BufferCollectionToken.Duplicate`], no

separate [`fuchsia.sysmem2/Node.Sync`] is needed after calling this

method, because the sync step is included in this call, at the cost of a

round trip during this call.

All tokens must be turned in to sysmem via

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] or

[`fuchsia.sysmem2/Node.Release`] for a `BufferCollection` to

successfully allocate buffers (or to logically allocate buffers in the

case of subtrees involving

[`fuchsia.sysmem2/BufferCollectionToken.AttachToken`]).

All table fields are currently required.

+ request `rights_attenuation_mask` In each entry of

`rights_attenuation_masks`, rights bits that are zero will be absent

in the buffer VMO rights obtainable via the corresponding returned

token. This allows an initiator or intermediary participant to

attenuate the rights available to a participant. This does not allow a

participant to gain rights that the participant doesn't already have.

The value `ZX_RIGHT_SAME_RIGHTS` can be used to specify that no

attenuation should be applied.

- response `tokens` The client ends of each newly created token.

Create an additional [`fuchsia.sysmem2/BufferCollectionToken`] from this

one, referring to the same buffer collection.

The created token is a child of this token in the

[`fuchsia.sysmem2/Node`] heirarchy.

This method can be used to add a participant, by transferring the newly

created token to another participant.

This one-way message can be used instead of the two-way

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] FIDL call in

performance sensitive cases where it would be undesireable to wait for

sysmem to respond to

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] or when the

client code isn't structured to make it easy to duplicate all the needed

tokens at once.

After sending one or more `Duplicate` messages, and before sending the

newly created child tokens to other participants (or to other

[`fuchsia.sysmem2/Allocator`] channels), the client must send a

[`fuchsia.sysmem2/Node.Sync`] and wait for the `Sync` response. The

`Sync` call can be made on the token, or on the `BufferCollection`

obtained by passing this token to `BindSharedCollection`. Either will

ensure that the server knows about the tokens created via `Duplicate`

before the other participant sends the token to the server via separate

`Allocator` channel.

All tokens must be turned in via

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] or

[`fuchsia.sysmem2/Node.Release`] for a `BufferCollection` to

successfully allocate buffers.

All table fields are currently required.

+ request `rights_attenuation_mask` The rights bits that are zero in

this mask will be absent in the buffer VMO rights obtainable via the

client end of `token_request`. This allows an initiator or

intermediary participant to attenuate the rights available to a

delegate participant. This does not allow a participant to gain rights

that the participant doesn't already have. The value

`ZX_RIGHT_SAME_RIGHTS` can be used to specify that no attenuation

should be applied.

+ These values for rights_attenuation_mask result in no attenuation:

+ `ZX_RIGHT_SAME_RIGHTS` (preferred)

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

computed)

+ 0 (deprecated - do not use 0 - an ERROR will go to the log)

+ request `token_request` is the server end of a `BufferCollectionToken`

channel. The client end of this channel acts as another participant in

the shared buffer collection.

Set this [`fuchsia.sysmem2/BufferCollectionToken`] to dispensable.

When the `BufferCollectionToken` is converted to a

[`fuchsia.sysmem2/BufferCollection`], the dispensable status applies to

the `BufferCollection` also.

Normally, if a client closes a [`fuchsia.sysmem2/BufferCollection`]

client end without having sent

[`fuchsia.sysmem2/BufferCollection.Release`] first, the

`BufferCollection` [`fuchisa.sysmem2/Node`] will fail, which also

propagates failure to the parent [`fuchsia.sysmem2/Node`] and so on up

to the root `Node`, which fails the whole buffer collection. In

contrast, a dispensable `Node` can fail after buffers are allocated

without causing failure of its parent in the [`fuchsia.sysmem2/Node`]

heirarchy.

The dispensable `Node` participates in constraints aggregation along

with its parent before buffer allocation. If the dispensable `Node`

fails before buffers are allocated, the failure propagates to the

dispensable `Node`'s parent.

After buffers are allocated, failure of the dispensable `Node` (or any

child of the dispensable `Node`) does not propagate to the dispensable

`Node`'s parent. Failure does propagate from a normal child of a

dispensable `Node` to the dispensable `Node`. Failure of a child is

blocked from reaching its parent if the child is attached using

[`fuchsia.sysmem2/BufferCollection.AttachToken`], or if the child is

dispensable and the failure occurred after allocation.

A dispensable `Node` can be used in cases where a participant needs to

provide constraints, but after buffers are allocated, the participant

can fail without causing buffer collection failure from the parent

`Node`'s point of view.

In contrast, `BufferCollection.AttachToken` can be used to create a

`BufferCollectionToken` which does not participate in constraints

aggregation with its parent `Node`, and whose failure at any time does

not propagate to its parent `Node`, and whose potential delay providing

constraints does not prevent the parent `Node` from completing its

buffer allocation.

An initiator (creator of the root `Node` using

[`fuchsia.sysmem2/Allocator.AllocateSharedCollection`]) may in some

scenarios choose to initially use a dispensable `Node` for a first

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 `BufferCollectionToken` created with `AttachToken`.

Normally a client will `SetDispensable` on a `BufferCollectionToken`

shortly before sending the dispensable `BufferCollectionToken` to a

delegate participant. Because `SetDispensable` prevents propagation of

child `Node` failure to parent `Node`(s), if the client was relying on

noticing child failure via failure of the parent `Node` retained by the

client, the client may instead need to notice failure via other means.

If other means aren't available/convenient, the client can instead

retain the dispensable `Node` and create a child `Node` under that to

send to the delegate participant, retaining this `Node` in order to

notice failure of the subtree rooted at this `Node` via this `Node`'s

ZX_CHANNEL_PEER_CLOSED signal, and take whatever action is appropriate

(e.g. starting a new instance of the delegate participant and handing it

a `BufferCollectionToken` created using

[`fuchsia.sysmem2/BufferCollection.AttachToken`], or propagate failure

and clean up in a client-specific way).

While it is possible (and potentially useful) to `SetDispensable` on a

direct child of a `BufferCollectionTokenGroup` `Node`, it isn't possible

to later replace a failed dispensable `Node` that was a direct child of

a `BufferCollectionTokenGroup` with a new token using `AttachToken`

(since there's no `AttachToken` on a group). Instead, to enable

`AttachToken` replacement in this case, create an additional

non-dispensable token that's a direct child of the group and make the

existing dispensable token a child of the additional token. This way,

the additional token that is a direct child of the group has

`BufferCollection.AttachToken` which can be used to replace the failed

dispensable token.

`SetDispensable` on an already-dispensable token is idempotent.

Create a logical OR among a set of tokens, called a

[`fuchsia.sysmem2/BufferCollectionTokenGroup`].

Most sysmem clients and many participants don't need to care about this

message or about `BufferCollectionTokenGroup`(s). However, in some cases

a participant wants to attempt to include one set of delegate

participants, but if constraints don't combine successfully that way,

fall back to a different (possibly overlapping) set of delegate

participants, and/or fall back to a less demanding strategy (in terms of

how strict the [`fuchisa.sysmem2/BufferCollectionConstraints`] are,

across all involved delegate participants). In such cases, a

`BufferCollectionTokenGroup` is useful.

A `BufferCollectionTokenGroup` is used to create a 1 of N OR among N

child [`fuchsia.sysmem2/BufferCollectionToken`](s). The child tokens

which are not selected during aggregation will fail (close), which a

potential participant should notice when their `BufferCollection`

channel client endpoint sees PEER_CLOSED, allowing the participant to

clean up the speculative usage that didn't end up happening (this is

simimlar to a normal `BufferCollection` server end closing on failure to

allocate a logical buffer collection or later async failure of a buffer

collection).

See comments on protocol `BufferCollectionTokenGroup`.

Any `rights_attenuation_mask` or `AttachToken`/`SetDispensable` to be

applied to the whole group can be achieved with a

`BufferCollectionToken` for this purpose as a direct parent of the

`BufferCollectionTokenGroup`.

All table fields are currently required.

+ request `group_request` The server end of a

`BufferCollectionTokenGroup` channel to be served by sysmem.