class SetDispensable

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.