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.

Wait until all buffers are allocated.

This FIDL call completes when buffers have been allocated, or completes

with some failure detail if allocation has been attempted but failed.

The following must occur before buffers will be allocated:

* All [`fuchsia.sysmem2/BufferCollectionToken`](s) of the buffer

collection must be turned in via `BindSharedCollection` to get a

[`fuchsia.sysmem2/BufferCollection`] (for brevity, this is assuming

[`fuchsia.sysmem2/BufferCollection.AttachToken`] isn't being used),

or have had [`fuchsia.sysmem2/BufferCollectionToken.Release`] sent

to them.

* All [`fuchsia.sysmem2/BufferCollection`](s) of the buffer collection

must have had [`fuchsia.sysmem2/BufferCollection.SetConstraints`]

sent to them, or had [`fuchsia.sysmem2/BufferCollection.Release`]

sent to them.

- result `buffer_collection_info` The VMO handles and other related

info.

* error `[fuchsia.sysmem2/Error.NO_MEMORY]` The request is valid but

cannot be fulfilled due to resource exhaustion.

* error `[fuchsia.sysmem2/Error.PROTOCOL_DEVIATION`] The request is

malformed.

* error `[fuchsia.sysmem2/Error.CONSTRAINTS_INTERSECTION_EMPTY`] The

request is valid but cannot be satisfied, perhaps due to hardware

limitations. This can happen if participants have incompatible

constraints (empty intersection, roughly speaking). See the log for

more info. In cases where a participant could potentially be treated

as optional, see [`BufferCollectionTokenGroup`]. When using

[`fuchsia.sysmem2/BufferCollection.AttachToken`], this will be the

error code if there aren't enough buffers in the pre-existing

collection to satisfy the constraints set on the attached token and

any sub-tree of tokens derived from the attached token.

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

Checks whether all the buffers have been allocated, in a polling

fashion.

* If the buffer collection has been allocated, returns success.

* If the buffer collection failed allocation, returns the same

[`fuchsia.sysmem2/Error`] as

[`fuchsia.sysmem2/BufferCollection/WaitForAllBuffersAllocated`] would

return.

* error [`fuchsia.sysmem2/Error.PENDING`] The buffer collection hasn't

attempted allocation yet. This means that WaitForAllBuffersAllocated

would not respond quickly.

Allocates 48 bytes of message buffer on the stack. No heap allocation necessary.