class BufferCollectionTokenGroup

The sysmem implementation is consistent with a logical / conceptual model of

allocation / logical allocation as follows:

As usual, a logical allocation considers either the root and all nodes with

connectivity to the root that don't transit a [`fuchsia.sysmem2/Node`]

created with [`fuchsia.sysmem2/BufferCollection.AttachToken`], or a subtree

rooted at an `AttachToken` `Node` and all `Node`(s) with connectivity to

that subtree that don't transit another `AttachToken`. This is called the

logical allocation pruned subtree, or pruned subtree for short.

During constraints aggregation, each

[`fuchsia.sysmem2/BufferCollectionTokenGroup`] will select a single child

`Node` among its direct children. The rest of the children will appear to

fail the logical allocation, while the selected child may succeed.

When more than one `BufferCollectionTokenGroup` exists in the overall

logical allocation pruned subtree, the relative priority between two groups

is equivalent to their ordering in a DFS pre-order iteration of the tree,

with parents higher priority than children, and left children higher

priority than right children.

When a particular child of a group is selected (whether provisionally during

a constraints aggregation attempt, or as a final selection), the

non-selection of other children of the group will "hide" any other groups

under those non-selected children.

Within a logical allocation, aggregation is attempted first by provisionally

selecting child 0 of the highest-priority group, and child 0 of the next

highest-priority group that isn't hidden by the provisional selections so

far, etc.

If that aggregation attempt fails, aggregation will be attempted with the

ordinal 0 child of all the same groups except the lowest priority non-hidden

group which will provisionally select its ordinal 1 child (and then child 2

and so on). If a new lowest-priority group is un-hidden as provisional

selections are updated, that newly un-hidden lowest-priority group has all

its children considered in order, before changing the provisional selection

in the former lowest-priority group. In terms of result, this is equivalent

to systematic enumeration of all possible combinations of choices in a

counting-like order updating the lowest-priority group the most often and

the highest-priority group the least often. Rather than actually attempting

aggregation with all the combinations, we can skip over combinations which

are redundant/equivalent due to hiding without any change to the result.

Attempted constraint aggregations of enumerated non-equivalent combinations

of choices continue in this manner until either (a) all aggregation attempts

fail in which case the overall logical allocation fails, or (b) until an

attempted aggregation succeeds, in which case buffer allocation (if needed;

if this is the pruned subtree rooted at the overall root `Node`) is

attempted once. If buffer allocation based on the first successful

constraints aggregation fails, the overall logical allocation fails (there

is no buffer allocation retry / re-attempt). If buffer allocation succeeds

(or is not needed due to being a pruned subtree that doesn't include the

root), the logical allocation succeeds.

If this prioritization scheme cannot reasonably work for your usage of

sysmem, please don't hesitate to contact sysmem folks to discuss potentially

adding a way to achieve what you need.

Please avoid creating a large number of `BufferCollectionTokenGroup`(s) per

logical allocation, especially with large number of children overall, and

especially in cases where aggregation may reasonably be expected to often

fail using ordinal 0 children and possibly with later children as well.

Sysmem mitigates potentially high time complexity of evaluating too many

child combinations/selections across too many groups by simply failing

logical allocation beyond a certain (fairly high, but not huge) max number

of considered group child combinations/selections. More advanced (and more

complicated) mitigation is not anticipated to be practically necessary or

worth the added complexity. Please contact sysmem folks if the max limit is

getting hit or if you anticipate it getting hit, to discuss potential

options.

Prefer to use multiple [`fuchsia.sysmem2/ImageFormatConstraints`] in a

single [`fuchsia.sysmem2/BufferCollectionConstraints`] when feasible (when a

participant just needs to express the ability to work with more than a

single [`fuchsia.images2/PixelFormat`], with sysmem choosing which

`PixelFormat` to use among those supported by all participants).

Similar to [`fuchsia.sysmem2/BufferCollectionToken`] and

[`fuchsia.sysmem2/BufferCollection`], closure of the

`BufferCollectionTokenGroup` channel without sending

[`fuchsia.sysmem2/Node.Release`] first will cause buffer collection failure

(or subtree failure if using

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

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

`BufferCollectionTokenGroup` is part of a subtree under such a node that

doesn't propagate failure to its parent).

Epitaphs are not used in this protocol.