class BufferCollectionTokenGroup

The sysmem implementation is guaranteed to be consistent with a logical /

conceptual model as follows:

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

connectivity to the root that don't transit an AttachToken(), or a sub-tree

rooted at an AttachToken() token and all nodes with connectivity to that

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

logical allocation pruned sub-tree, or pruned sub-tree for short.

During constraints aggregation, each BufferCollectionTokenGroup will select

a single child token among its 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 sub-tree, 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 can potentially "hide" other

groups under those non-selected children.

Within a logical allocation, aggregation is attempted first by provisionally

selecting the 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 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) is

attempted once. If buffer allocation based on the first successful

aggregation fails, the overall logical allocation fails (there is no buffer

allocation retry / re-attempt). If buffer allocation succeeds (or is not

needed), the logical allocation succeeds.

If this prioritization scheme cannot reasonably work for your usage of

sysmem, please 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. We

anticipate mitigating 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 ImageFormatConstraints in a single

BufferCollectionConstraints when feasible (when a participant just needs to

express the ability to work with more than a single PixelFormat, with

sysmem choosing which PixelFormat to use among those supported by all

participants).

Similar to BufferCollectionToken and BufferCollection, closure of the

BufferCollectionTokenGroup channel without sending Close() first will cause

logical buffer collection failure (or sub-tree failure if using

SetDispensable() or AttachToken() and the BufferCollectionTokenGroup is part

of a sub-tree under such a node that doesn't propagate failure to its

parent).