class WireWeakAsyncClientImpl

Ensure that previous messages have been received server side. This is

particularly useful after previous messages that created new tokens,

because a token must be known to the sysmem server before sending the

token to another participant.

Calling [`fuchsia.sysmem2/BufferCollectionToken.Sync`] on a token that

isn't/wasn't a valid token risks the `Sync` stalling forever. See

[`fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken`] for one way

to mitigate the possibility of a hostile/fake

[`fuchsia.sysmem2/BufferCollectionToken`] at the cost of one round trip.

Another way is to pass the token to

[`fuchsia.sysmem2/Allocator/BindSharedCollection`], which also validates

the token as part of exchanging it for a

[`fuchsia.sysmem2/BufferCollection`] channel, and

[`fuchsia.sysmem2/BufferCollection.Sync`] can then be used without risk

of stalling.

After creating one or more [`fuchsia.sysmem2/BufferCollectionToken`](s)

and then starting and completing a `Sync`, it's then safe to send the

`BufferCollectionToken` client ends to other participants knowing the

server will recognize the tokens when they're sent by the other

participants to sysmem in a

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] message. This is an

efficient way to create tokens while avoiding unnecessary round trips.

Other options include waiting for each

[`fuchsia.sysmem2/BufferCollectionToken.Duplicate`] to complete

individually (using separate call to `Sync` after each), or calling

[`fuchsia.sysmem2/BufferCollection.Sync`] after a token has been

converted to a `BufferCollection` via

[`fuchsia.sysmem2/Allocator.BindSharedCollection`], or using

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] which includes

the sync step and can create multiple tokens at once.

Allocates 16 bytes of request buffer on the stack. The callback is stored on the heap.

This gets a handle that can be used as a parameter to

[`fuchsia.sysmem2/Node.IsAlternateFor`] called on any

[`fuchsia.sysmem2/Node`]. This handle is only for use as proof that the

client obtained this handle from this `Node`.

Because this is a get not a set, no [`fuchsia.sysmem2/Node.Sync`] is

needed between the `GetNodeRef` and the call to `IsAlternateFor`,

despite the two calls typically being on different channels.

See also [`fuchsia.sysmem2/Node.IsAlternateFor`].

All table fields are currently required.

- response `node_ref` This handle can be sent via `IsAlternateFor` on a

different `Node` channel, to prove that the client obtained the handle

from this `Node`.

Allocates 16 bytes of request buffer on the stack. The callback is stored on the heap.

Check whether the calling [`fuchsia.sysmem2/Node`] is in a subtree

rooted at a different child token of a common parent

[`fuchsia.sysmem2/BufferCollectionTokenGroup`], in relation to the

passed-in `node_ref`.

This call is for assisting with admission control de-duplication, and

with debugging.

The `node_ref` must be obtained using

[`fuchsia.sysmem2/Node.GetNodeRef`].

The `node_ref` can be a duplicated handle; it's not necessary to call

`GetNodeRef` for every call to [`fuchsia.sysmem2/Node.IsAlternateFor`].

If a calling token may not actually be a valid token at all due to a

potentially hostile/untrusted provider of the token, call

[`fuchsia.sysmem2/Allocator.ValidateBufferCollectionToken`] first

instead of potentially getting stuck indefinitely if `IsAlternateFor`

never responds due to a calling token not being a real token (not really

talking to sysmem). Another option is to call

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] with this token first

which also validates the token along with converting it to a

[`fuchsia.sysmem2/BufferCollection`], then call `IsAlternateFor`.

All table fields are currently required.

- response `is_alternate`

- true: The first parent node in common between the calling node and

the `node_ref` `Node` is a `BufferCollectionTokenGroup`. This means

that the calling `Node` and the `node_ref` `Node` will not have both

their constraints apply - rather sysmem will choose one or the other

of the constraints - never both. This is because only one child of

a `BufferCollectionTokenGroup` is selected during logical

allocation, with only that one child's subtree contributing to

constraints aggregation.

- false: The first parent node in common between the calling `Node`

and the `node_ref` `Node` is not a `BufferCollectionTokenGroup`.

Currently, this means the first parent node in common is a

`BufferCollectionToken` or `BufferCollection` (regardless of not

`Release`ed). This means that the calling `Node` and the `node_ref`

`Node` may have both their constraints apply during constraints

aggregation of the logical allocation, if both `Node`(s) are

selected by any parent `BufferCollectionTokenGroup`(s) involved. In

this case, there is no `BufferCollectionTokenGroup` that will

directly prevent the two `Node`(s) from both being selected and

their constraints both aggregated, but even when false, one or both

`Node`(s) may still be eliminated from consideration if one or both

`Node`(s) has a direct or indirect parent

`BufferCollectionTokenGroup` which selects a child subtree other

than the subtree containing the calling `Node` or `node_ref` `Node`.

* error `[fuchsia.sysmem2/Error.NOT_FOUND]` The node_ref wasn't

associated with the same buffer collection as the calling `Node`.

Another reason for this error is if the `node_ref` is an

[`zx.Handle.EVENT`] handle with sufficient rights, but isn't actually

a real `node_ref` obtained from `GetNodeRef`.

* error `[fuchsia.sysmem2/Error.PROTOCOL_DEVIATION]` The caller passed a

`node_ref` that isn't a [`zx.Handle:EVENT`] handle , or doesn't have

the needed rights expected on a real `node_ref`.

* No other failing status codes are returned by this call. However,

sysmem may add additional codes in future, so the client should have

sensible default handling for any failing status code.

Allocates 40 bytes of request buffer on the stack. The callback is stored on the heap.

Get the buffer collection ID. This ID is also available from

[`fuchsia.sysmem2/Allocator.GetVmoInfo`] (along with the `buffer_index`

within the collection).

This call is mainly useful in situations where we can't convey a

[`fuchsia.sysmem2/BufferCollectionToken`] or

[`fuchsia.sysmem2/BufferCollection`] directly, but can only convey a VMO

handle, which can be joined back up with a `BufferCollection` client end

that was created via a different path. Prefer to convey a

`BufferCollectionToken` or `BufferCollection` directly when feasible.

Trusting a `buffer_collection_id` value from a source other than sysmem

is analogous to trusting a koid value from a source other than zircon.

Both should be avoided unless really necessary, and both require

caution. In some situations it may be reasonable to refer to a

pre-established `BufferCollection` by `buffer_collection_id` via a

protocol for efficiency reasons, but an incoming value purporting to be

a `buffer_collection_id` is not sufficient alone to justify granting the

sender of the `buffer_collection_id` any capability. The sender must

first prove to a receiver that the sender has/had a VMO or has/had a

`BufferCollectionToken` to the same collection by sending a handle that

sysmem confirms is a valid sysmem handle and which sysmem maps to the

`buffer_collection_id` value. The receiver should take care to avoid

assuming that a sender had a `BufferCollectionToken` in cases where the

sender has only proven that the sender had a VMO.

- response `buffer_collection_id` This ID is unique per buffer

collection per boot. Each buffer is uniquely identified by the

`buffer_collection_id` and `buffer_index` together.

Allocates 16 bytes of request buffer on the stack. The callback is stored on the heap.

Create 1 or more child tokens at once, synchronously. In contrast to

[`fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChild`], no

[`fuchsia.sysmem2/Node.Sync`] is required before passing the client end

of a returned token to

[`fuchsia.sysmem2/Allocator/BindSharedCollection`].

The lower-index child tokens are higher priority (attempted sooner) than

higher-index child tokens.

As per all child tokens, successful aggregation will choose exactly one

child among all created children (across all children created across

potentially multiple calls to

[`fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChild`] and

[`fuchsia.sysmem2/BufferCollectionTokenGroup.CreateChildrenSync`]).

The maximum permissible total number of children per group, and total

number of nodes in an overall tree (from the root) are capped to limits

which are not configurable via these protocols.

Sending CreateChildrenSync after AllChildrenPresent is not permitted;

this will fail the group's subtree and close the connection.

After all children have been created, send AllChildrenPresent.

+ request `rights_attentuation_masks` The size of the

`rights_attentuation_masks` determines the number of created child

tokens. The value ZX_RIGHT_SAME_RIGHTS doesn't attenuate any rights.

The value 0xFFFFFFFF is a synonym for ZX_RIGHT_SAME_RIGHTS. For any

other value, each 0 bit in the mask attenuates that right.

- response `tokens` The created child tokens.

Allocates 312 bytes of request buffer on the stack. The callback is stored on the heap.