class WireWeakSyncClientImpl

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 48 bytes of message buffer on the stack. No heap allocation necessary.

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. Response is heap-allocated.

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. Response is heap-allocated.

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. Response is heap-allocated.

Create additional [`fuchsia.sysmem2/BufferCollectionToken`](s) from this

one, referring to the same buffer collection.

The created tokens are children of this token in the

[`fuchsia.sysmem2/Node`] heirarchy.

This method can be used to add more participants, by transferring the

newly created tokens to additional participants.

A new token will be returned for each entry in the

`rights_attenuation_masks` array.

If the called token may not actually be a valid token due to a

potentially hostile/untrusted provider of the token, consider using

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

instead of potentially getting stuck indefinitely if

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] never responds

due to the calling token not being a real token.

In contrast to [`fuchsia.sysmem2/BufferCollectionToken.Duplicate`], no

separate [`fuchsia.sysmem2/Node.Sync`] is needed after calling this

method, because the sync step is included in this call, at the cost of a

round trip during this call.

All tokens must be turned in to sysmem via

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

[`fuchsia.sysmem2/Node.Release`] for a `BufferCollection` to

successfully allocate buffers (or to logically allocate buffers in the

case of subtrees involving

[`fuchsia.sysmem2/BufferCollectionToken.AttachToken`]).

All table fields are currently required.

+ request `rights_attenuation_mask` In each entry of

`rights_attenuation_masks`, rights bits that are zero will be absent

in the buffer VMO rights obtainable via the corresponding returned

token. This allows an initiator or intermediary participant to

attenuate the rights available to a participant. This does not allow a

participant to gain rights that the participant doesn't already have.

The value `ZX_RIGHT_SAME_RIGHTS` can be used to specify that no

attenuation should be applied.

- response `tokens` The client ends of each newly created token.

Allocates 312 bytes of request buffer on the stack. Response is heap-allocated.