class WireWeakSyncClientImpl

Checks whether a [`fuchsia.sysmem2/BufferCollectionToken`] is known to

the sysmem server.

With this call, the client can determine whether an incoming token is a

real sysmem token that is known to the sysmem server, without any risk

of getting stuck waiting forever on a potentially fake token to complete

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] or

[`fuchsia.sysmem2/BufferCollectionToken.Sync`] (or any other two-way

FIDL message). In cases where the client trusts the source of the token

to provide a real token, this call is not typically needed outside of

debugging.

If the validate fails sometimes but succeeds other times, the source of

the token may itself not be calling

[`fuchsia.sysmem2/BufferCollectionToken.Sync`] or

[`fuchsia.sysmem2/BufferCollection.Sync`] after creating/duplicating the

token but before sending the token to the current client. It may be more

convenient for the source to use

[`fuchsia.sysmem2/BufferCollectionToken.DuplicateSync`] to duplicate

token(s), since that call has the sync step built in. Or, the buffer

collection may be failing before this call is processed by the sysmem

server, as buffer collection failure cleans up sysmem's tracking of

associated tokens.

This call has no effect on any token.

+ request `token_server_koid` The koid of the server end of a channel

that might be a BufferCollectionToken channel. This can be obtained

via `zx_object_get_info` `ZX_INFO_HANDLE_BASIC` `related_koid`.

- response `is_known` true means sysmem knew of the token at the time

sysmem processed the request, but doesn't guarantee that the token is

still valid by the time the client receives the reply. What it does

guarantee is that the token at least was a real token, so a two-way

call to the token won't stall forever (will fail or succeed fairly

quickly, not stall). This can already be known implicitly if the

source of the token can be trusted to provide a real token. A false

value means the token wasn't known to sysmem at the time sysmem

processed this call, but the token may have previously been valid, or

may yet become valid. Or if the sender of the token isn't trusted to

provide a real token, the token may be fake. It's the responsibility

of the sender to sync with sysmem to ensure that previously

created/duplicated token(s) are known to sysmem, before sending the

token(s) to other participants.

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

Given a handle to a sysmem-provided VMO, this returns additional info

about the corresponding sysmem logical buffer.

Most callers will duplicate a VMO handle first and send the duplicate to

this call.

If the client has created a child VMO of a sysmem-provided VMO, that

child VMO isn't considered a "sysmem VMO" for purposes of this call.

+ request `vmo` A handle to a sysmem-provided VMO (or see errors).

- response `buffer_collection_id` The buffer collection ID, which is

unique per logical buffer collection per boot.

- response `buffer_index` The buffer index of the buffer within the

buffer collection. This is the same as the index of the buffer within

[`fuchsia.sysmem2/BufferCollectionInfo.buffers`]. The `buffer_index`

is the same for all sysmem-delivered VMOs corresponding to the same

logical buffer, even if the VMO koids differ. The `buffer_index` is

only unique across buffers of a buffer collection. For a given buffer,

the combination of `buffer_collection_id` and `buffer_index` is unique

per boot.

- response `close_weak_asap` Iff `vmo` is a handle to a weak sysmem VMO,

the `close_weak_asap` field will be set in the response. This handle

will signal `ZX_EVENTPAIR_PEER_CLOSED` when all weak VMO handles to

the buffer should be closed as soon as possible. This is signalled

shortly after all strong sysmem VMOs to the buffer are closed

(including any held indirectly via strong `BufferCollectionToken` or

strong `BufferCollection`). Failure to close all weak sysmem VMO

handles to the buffer quickly upon `ZX_EVENTPAIR_PEER_CLOSED` is

considered a VMO leak caused by the client still holding a weak sysmem

VMO handle and results in loud complaints to the log by sysmem. The

buffers of a collection can be freed independently of each other. The

`ZX_EVENTPAIR_PEER_CLOSED` may already be signalled before the

response arrives at the client. A client that isn't prepared to handle

weak sysmem VMOs, on seeing this field set, can close all handles to

the buffer and fail any associated request.

* error `[fuchsia.sysmem2/Error.NOT_FOUND]` - the vmo isn't a sysmem

VMO. Both strong and weak sysmem VMOs can be passed to this call, and

the VMO handle passed in to this call itself keeps the VMO's info

alive for purposes of responding to this call. Because of this,

ZX_ERR_NOT_FOUND errors are unambiguous (even if there are no other

handles to the VMO when calling; even if other handles are closed

before the GetVmoInfo response arrives at the client).

* error `[fuchsia.sysmem2/Error.HANDLE_ACCESS_DENIED]` The vmo isn't

capable of being used with GetVmoInfo due to rights/capability

attenuation. The VMO needs to be usable with [`zx_vmo_get_info`] with

topic [`ZX_INFO_HANDLE_BASIC`].

* error `[fuchsia.sysmem2/Error.UNSPECIFIED]` The request failed for an

unspecified reason. See the log for more info.

* error `[fuchsia.sysmem2/Error.PROTOCOL_DEVIATION]` The vmo field

wasn't set, or there was some other problem with the request field(s).

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