class SetDispensable

A dispensable token can fail after buffers are logically allocated

without causing failure of its parent (if any).

The dispensable token participates in constraints aggregation along with

its parent before logical buffer allocation. If the dispensable token

fails before buffers are logically allocated, the failure propagates to

the dispensable token's parent.

After buffers are logically allocated, failure of the dispensable token

(or any child of the dispensable token) does not propagate to the

dispensable token's parent. 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.

A dispensable token 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's

point of view.

In contrast, AttachToken() can be used to create a token which does not

participate in constraints aggregation with its parent, and whose

failure at any time does not propagate to its parent, and whose delay

providing constraints does not prevent the parent from completing its

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

If a client uses this message, the client should not rely on the

client's own BufferCollectionToken or BufferCollection channel to close

from the server end due to abrupt failure of any BufferCollectionToken

or BufferCollection that the client has SetDispensable() and given out

to another process. For this reason, the client should take extra care

to notice failure of that other process via other means.

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

direct child of a BufferCollectionTokenGroup, it isn't possible to later

replace a failed dispensable token that was a direct child of a group

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 (node) that's a direct child

of the group and make the existing dispensable token a child of the

additional token (node). This way, the additional token (node) 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.