Struct BufferCollectionTokenGroup 

pub struct BufferCollectionTokenGroup;

The type corresponding to the BufferCollectionTokenGroup protocol. 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.

Trait Implementations

impl Debug for BufferCollectionTokenGroup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<___H, ___T> DispatchClientMessage<___H, ___T> for BufferCollectionTokenGroup

where ___H: BufferCollectionTokenGroupClientHandler<___T> + Send, ___T: Transport,

async fn on_event( handler: &mut ___H, ordinal: u64, flexibility: Flexibility, body: Body<___T>, ) -> Result<(), ProtocolError<___T::Error>>

Handles a received client event with the given handler.

impl<___H, ___T> DispatchLocalClientMessage<___H, ___T> for BufferCollectionTokenGroup

where ___H: BufferCollectionTokenGroupLocalClientHandler<___T>, ___T: Transport,

async fn on_event( handler: &mut ___H, ordinal: u64, flexibility: Flexibility, body: Body<___T>, ) -> Result<(), ProtocolError<___T::Error>>

Handles a received client event with the given handler.

impl<___H, ___T> DispatchLocalServerMessage<___H, ___T> for BufferCollectionTokenGroup

where ___H: BufferCollectionTokenGroupLocalServerHandler<___T>, ___T: Transport, for<'de> NodeSetNameRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeSetDebugClientInfoRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeSetDebugTimeoutLogDeadlineRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeIsAlternateForRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeSetWeakOkRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeAttachNodeTrackingRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> BufferCollectionTokenGroupCreateChildRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> BufferCollectionTokenGroupCreateChildrenSyncRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>,

async fn on_one_way( handler: &mut ___H, ordinal: u64, flexibility: Flexibility, body: Body<___T>, ) -> Result<(), ProtocolError<<___T as Transport>::Error>>

Handles a received server one-way message with the given handler.

async fn on_two_way( handler: &mut ___H, ordinal: u64, flexibility: Flexibility, body: Body<___T>, responder: Responder<___T>, ) -> Result<(), ProtocolError<<___T as Transport>::Error>>

Handles a received server two-way message with the given handler.

impl<___H, ___T> DispatchServerMessage<___H, ___T> for BufferCollectionTokenGroup

where ___H: BufferCollectionTokenGroupServerHandler<___T> + Send, ___T: Transport, for<'de> NodeSetNameRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeSetDebugClientInfoRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeSetDebugTimeoutLogDeadlineRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeIsAlternateForRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeSetWeakOkRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> NodeAttachNodeTrackingRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> BufferCollectionTokenGroupCreateChildRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>, for<'de> BufferCollectionTokenGroupCreateChildrenSyncRequest<'de>: Decode<<<___T as Transport>::RecvBuffer as AsDecoder<'de>>::Decoder, Constraint = ()>,

async fn on_one_way( handler: &mut ___H, ordinal: u64, flexibility: Flexibility, body: Body<___T>, ) -> Result<(), ProtocolError<<___T as Transport>::Error>>

Handles a received server one-way message with the given handler.

async fn on_two_way( handler: &mut ___H, ordinal: u64, flexibility: Flexibility, body: Body<___T>, responder: Responder<___T>, ) -> Result<(), ProtocolError<<___T as Transport>::Error>>

Handles a received server two-way message with the given handler.

impl<___T> HasConnectionHandles<___T> for BufferCollectionTokenGroup

where ___T: Transport,

type Client = BufferCollectionTokenGroupClient<___T>

The client for the protocol. It must be a #[repr(transparent)] wrapper around Client<T>.

type Server = BufferCollectionTokenGroupServer<___T>

The server for the protocol. It must be a #[repr(transparent)] wrapper around Server<T>.

impl HasTransport for BufferCollectionTokenGroup

Available on Fuchsia only.

type Transport = Channel

The default transport type for this protocol.

impl PartialEq for BufferCollectionTokenGroup

fn eq(&self, other: &BufferCollectionTokenGroup) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for BufferCollectionTokenGroup