class Allocator

Allocates a buffer collection on behalf of a single client (aka

initiator) who is also the only participant (from the point of view of

sysmem).

This call exists mainly for temp/testing purposes. This call skips the

[`fuchsia.sysmem2/BufferCollectionToken`] stage, so there's no way to

allow another participant to specify its constraints.

Real clients are encouraged to use

[`fuchsia.sysmem2/Allocator.AllocateSharedCollection`] instead, and to

let relevant participants directly convey their own constraints to

sysmem by sending `BufferCollectionToken`s to those participants.

+ request `collection_request` The server end of the

[`fuchsia.sysmem2/BufferCollection`].

Creates a root [`fuchsia.sysmem2/BufferCollectionToken`].

The `BufferCollectionToken` can be "duplicated" for distribution to

participants by using

[`fuchsia.sysmem2/BufferCollectionToken.Duplicate`]. Each

`BufferCollectionToken` can be converted into a

[`fuchsia.sysmem2.BufferCollection`] using

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

Buffer constraints can be set via

[`fuchsia.sysmem2/BufferCollection.SetConstraints`].

Success/failure to populate the buffer collection with buffers can be

determined from

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

Closing the client end of a `BufferCollectionToken` or

`BufferCollection` (without `Release` first) will fail all client ends

in the same failure domain, which by default is all client ends of the

buffer collection. See

[`fuchsia.sysmem2/BufferCollection.SetDispensable`] and

[`fuchsia.sysmem2/BufferCollection.AttachToken`] for ways to create

separate failure domains within a buffer collection.

Convert a [`fuchsia.sysmem2/BufferCollectionToken`] into a

[`fuchsia.sysmem2/BufferCollection`].

At the time of sending this message, the buffer collection hasn't yet

been populated with buffers - the participant must first also send

[`fuchsia.sysmem2/BufferCollection.SetConstraints`] via the

`BufferCollection` client end.

All `BufferCollectionToken`(s) duplicated from a root

`BufferCollectionToken` (created via `AllocateSharedCollection`) must be

"turned in" via `BindSharedCollection` (or `Release`ed), and all

existing `BufferCollection` client ends must have sent `SetConstraints`

before the logical BufferCollection will be populated with buffers (or

will fail if the overall set of constraints can't be satisfied).

+ request `token` The client endpoint of a channel whose server end was

sent to sysmem using

[`fuchsia.sysmem2/Allocator.AllocateSharedCollection`] or whose server

end was sent to sysmem using

[`fuchsia.sysmem2/BufferCollectionToken.Duplicate`]. The token is

being "turned in" in exchange for a

[`fuchsia.sysmem2/BufferCollection`].

+ request `buffer_collection_request` The server end of a

[`fuchsia.sysmem2/BufferCollection`] channel. The sender retains the

client end. The `BufferCollection` channel is a single participant's

connection to the logical buffer collection. Typically there will be

other participants with their own `BufferCollection` channel to the

logical buffer collection.

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.

Set information about the current client that can be used by sysmem to

help diagnose leaking memory and allocation stalls waiting for a

participant to send [`fuchsia.sysmem2/BufferCollection.SetConstraints`].

This sets the debug client info on all [`fuchsia.sysmem2/Node`](s)

subsequently created by this this [`fuchsia.sysmem2/Allocator`]

including any [`fuchsia.sysmem2/BufferCollection`](s) created via

[`fuchsia.sysmem2/Allocator.BindSharedCollection`] (in the absence of

any prior call to [`fuchsia.sysmem2/Allocator.SetDebugClientInfo`],

these `BufferCollection`(s) have the same initial debug client info as

the token turned in to create the `BufferCollection`).

This info can be subsequently overridden on a per-`Node` basis by

sending [`fuchsia.sysmem2/Node.SetDebugClientInfo`].

Sending [`fuchsia.sysmem2/Allocator.SetDebugClientInfo`] once per

`Allocator` is the most efficient way to ensure that all

[`fuchsia.sysmem2/Node`](s) will have at least some debug client info

set, and is also more efficient than separately sending the same debug

client info via [`fuchsia.sysmem2/Node.SetDebugClientInfo`] for each

created [`fuchsia.sysmem2/Node`].

+ request `name` This can be an arbitrary string, but the current

process name (see `fsl::GetCurrentProcessName`) is a good default.

+ request `id` This can be an arbitrary id, but the current process ID

(see `fsl::GetCurrentProcessKoid`) is a good default.

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).