pub struct AllocatorSynchronousProxy { /* private fields */ }
Implementations§
source§impl AllocatorSynchronousProxy
impl AllocatorSynchronousProxy
pub fn new(channel: Channel) -> Self
pub fn into_channel(self) -> Channel
sourcepub fn wait_for_event(
&self,
deadline: MonotonicTime,
) -> Result<AllocatorEvent, Error>
pub fn wait_for_event( &self, deadline: MonotonicTime, ) -> Result<AllocatorEvent, Error>
Waits until an event arrives and returns it. It is safe for other threads to make concurrent requests while waiting for an event.
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. TheBufferCollection
channel is a single participant’s connection to the logical buffer collection. Typically there will be other participants with their ownBufferCollection
channel to the logical buffer collection.
sourcepub fn validate_buffer_collection_token(
&self,
payload: &AllocatorValidateBufferCollectionTokenRequest,
___deadline: MonotonicTime,
) -> Result<AllocatorValidateBufferCollectionTokenResponse, Error>
pub fn validate_buffer_collection_token( &self, payload: &AllocatorValidateBufferCollectionTokenRequest, ___deadline: MonotonicTime, ) -> Result<AllocatorValidateBufferCollectionTokenResponse, Error>
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 viazx_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.
sourcepub fn set_debug_client_info(
&self,
payload: &AllocatorSetDebugClientInfoRequest,
) -> Result<(), Error>
pub fn set_debug_client_info( &self, payload: &AllocatorSetDebugClientInfoRequest, ) -> Result<(), Error>
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
subsequently created by this this [fuchsia.sysmem2/Allocator
]
including any fuchsia.sysmem2/BufferCollection
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
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 (seefsl::GetCurrentProcessName
) is a good default. - request
id
This can be an arbitrary id, but the current process ID (seefsl::GetCurrentProcessKoid
) is a good default.
sourcepub fn get_vmo_info(
&self,
payload: AllocatorGetVmoInfoRequest,
___deadline: MonotonicTime,
) -> Result<AllocatorGetVmoInfoResult, Error>
pub fn get_vmo_info( &self, payload: AllocatorGetVmoInfoRequest, ___deadline: MonotonicTime, ) -> Result<AllocatorGetVmoInfoResult, Error>
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
]. Thebuffer_index
is the same for all sysmem-delivered VMOs corresponding to the same logical buffer, even if the VMO koids differ. Thebuffer_index
is only unique across buffers of a buffer collection. For a given buffer, the combination ofbuffer_collection_id
andbuffer_index
is unique per boot. - response
close_weak_asap
Iffvmo
is a handle to a weak sysmem VMO, theclose_weak_asap
field will be set in the response. This handle will signalZX_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 strongBufferCollectionToken
or strongBufferCollection
). Failure to close all weak sysmem VMO handles to the buffer quickly uponZX_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. TheZX_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).
Trait Implementations§
source§impl Debug for AllocatorSynchronousProxy
impl Debug for AllocatorSynchronousProxy
source§impl SynchronousProxy for AllocatorSynchronousProxy
impl SynchronousProxy for AllocatorSynchronousProxy
§type Proxy = AllocatorProxy
type Proxy = AllocatorProxy
§type Protocol = AllocatorMarker
type Protocol = AllocatorMarker
Proxy
controls.