class WireWeakOnewayClientImpl

On a BufferCollectionToken channel:

Normally a participant will convert a BufferCollectionToken into a

BufferCollection view, but a participant is also free to Close() the

token (and then close the channel immediately or shortly later in

response to server closing its end), which avoids causing logical buffer

collection failure.  Normally an unexpected token channel close will

cause logical buffer collection failure (the only exceptions being

certain cases involving AttachToken() or SetDispensable()).

On a BufferCollection channel:

By default the server handles unexpected failure of a BufferCollection

by failing the whole logical buffer collection. Partly this is to

expedite closing VMO handles to reclaim memory when any participant

fails. If a participant would like to cleanly close a BufferCollection

view without causing logical buffer collection failure, the participant

can send Close() before closing the client end of the BufferCollection

channel. If this is the last BufferCollection view, the logical buffer

collection will still go away. The Close() can occur before or after

SetConstraints(). If before SetConstraints(), the buffer collection

won't require constraints from this node in order to allocate. If

after SetConstraints(), the constraints are retained and aggregated

along with any subsequent logical allocation(s), despite the lack of

channel connection.

On a BufferCollectionTokenGroup channel:

By default, unexpected failure of a BufferCollectionTokenGroup will

trigger failure of the logical BufferCollectionTokenGroup and will

propagate failure to its parent. To close a BufferCollectionTokenGroup

channel without failing the logical group or propagating failure, send

Close() before closing the channel client endpoint.

If Close() occurs before AllChildrenPresent(), the logical buffer

collection will still fail despite the Close() (because sysmem can't be

sure whether all relevant children were created, so it's ambiguous

whether all relevant constraints will be provided to sysmem). If

Close() occurs after AllChildrenPresent(), the children and all their

constraints remain intact (just as they would if the

BufferCollectionTokenGroup channel had remained open), and the close

doesn't trigger or propagate failure.

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

Set a name for VMOs in this buffer collection. The name may be truncated

shorter. The name only affects VMOs allocated after it's set - this call

does not rename existing VMOs. If multiple clients set different names

then the larger priority value will win.

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

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

help debug leaking memory and hangs waiting for constraints. |name| can

be an arbitrary string, but the current process name (see

fsl::GetCurrentProcessName()) is a good default. |id| can be an

arbitrary id, but the current process ID (see

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

Also used when verbose logging is enabled (see SetVerboseLogging()) to

indicate which client is closing their channel first, leading to

sub-tree failure (which can be normal if the purpose of the sub-tree is

over, but if happening earlier than expected, the

client-channel-specific name can help diagnose where the failure is

first coming from, from sysmem's point of view).

By default (unless overriden by this message or using

Allocator.SetDebugClientInfo()), a Node will copy info from its

parent Node at the time the child Node is created. While this can be

better than nothing, it's often better for each participant to use

Node.SetDebugClientInfo() or Allocator.SetDebugClientInfo() to keep the

info directly relevant to the current client. Also, SetVerboseLogging()

can be used to help disambiguate if a Node is suspected of having info

that was copied from its parent.

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

Sysmem logs a warning if not all clients have set constraints 5 seconds

after creating a collection. Clients can call this method to change

when the log is printed. If multiple client set the deadline, it's

unspecified which deadline will take effect.

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

Verbose logging includes constraints set via SetConstraints() from each

client along with info set via SetDebugClientInfo() and the structure of

the tree of Node(s).

Normally sysmem prints only a single line complaint when aggregation

fails, with just the specific detailed reason that aggregation failed,

with minimal context. While this is often enough to diagnose a problem

if only a small change was made and the system had been working before

the small change, it's often not particularly helpful for getting a new

buffer collection to work for the first time. Especially with more

complex trees of nodes, involving things like AttachToken(),

SetDispensable(), BufferCollectionTokenGroup nodes, and associated

sub-trees of nodes, verbose logging may help in diagnosing what the tree

looks like and why it's failing a logical allocation, or why a tree or

sub-tree is failing sooner than expected.

The intent of the extra logging is to be acceptable from a performance

point of view, if only enabled on a low number of buffer collections.

If we're not tracking down a bug, we shouldn't send this message.

If too many participants leave verbose logging enabled, we may end up

needing to require that system-wide sysmem verbose logging be permitted

via some other setting, to avoid sysmem spamming the log too much due to

this message.

This may be a NOP for some nodes due to intentional policy associated

with the node, if we don't trust a node enough to let it turn on verbose

logging.

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

This method can be used to add a participant prior to creating a shared

BufferCollection. It should only be used instead of DuplicateSync in

performance sensitive cases where it would be undesireable to wait for

sysmem to respond as part of each duplicate.

After sending one or more Duplicate() messages, and before sending the

created tokens to other participants (or to other Allocator channels),

the client should send a Sync() and wait for its response. The Sync()

call can be made on the token, or on the BufferCollection obtained by

passing this token to BindSharedCollection(). Either will ensure that

the server knows about the tokens created via Duplicate() before the

other participant sends the token to the server via separate Allocator

channel.

All tokens must be turned in via BindSharedCollection() or Close() for a

BufferCollection to be successfully created.

When a client calls BindSharedCollection() to turn in a

BufferCollectionToken, the server will process all Duplicate() messages

before closing down the BufferCollectionToken. This allows the client

to Duplicate() and immediately turn in the BufferCollectionToken using

BindSharedCollection, then later transfer the client end of token_request

to another participant - the server will notice the existence of the

token_request before considering this BufferCollectionToken fully closed.

`rights_attenuation_mask` rights bits that are zero in this mask will be

absent in the buffer VMO rights obtainable via the client end of

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

These values for rights_attenuation_mask result in no attenuation:

* ZX_RIGHT_SAME_RIGHTS (preferred)

* 0xFFFFFFFF (this is reasonable when an attenuation mask is computed)

* 0 (deprecated - do not use 0 - an ERROR will go to the log)

`token_request` is the server end of a BufferCollectionToken channel.

The client end of this channel acts as another participant in creating the

shared BufferCollection.

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

A dispensable token can fail after buffers are logically allocated

without causing failure of its parent (if any).

The dispensable token participates in constraints aggregation along with

its parent before logical buffer allocation. If the dispensable token

fails before buffers are logically allocated, the failure propagates to

the dispensable token's parent.

After buffers are logically allocated, failure of the dispensable token

(or any child of the dispensable token) does not propagate to the

dispensable token's parent. Failure does propagate from a normal

child of a dispensable token to the dispensable token. Failure

of a child is blocked from reaching its parent if the child is attached,

or if the child is dispensable and the failure occurred after logical

allocation.

A dispensable token can be used in cases where a participant needs to

provide constraints, but after buffers are allocated, the participant

can fail without causing buffer collection failure from the parent's

point of view.

In contrast, AttachToken() can be used to create a token which does not

participate in constraints aggregation with its parent, and whose

failure at any time does not propagate to its parent, and whose delay

providing constraints does not prevent the parent from completing its

buffer allocation.

An initiator may in some scenarios choose to initially use a dispensable

token for a given instance of a participant, and then later if the first

instance of that participant fails, a new second instance of that

participant my be given a token created with AttachToken().

If a client uses this message, the client should not rely on the

client's own BufferCollectionToken or BufferCollection channel to close

from the server end due to abrupt failure of any BufferCollectionToken

or BufferCollection that the client has SetDispensable() and given out

to another process. For this reason, the client should take extra care

to notice failure of that other process via other means.

While it is possible (and potentially useful) to SetDispensable() on a

direct child of a BufferCollectionTokenGroup, it isn't possible to later

replace a failed dispensable token that was a direct child of a group

with a new token using AttachToken() (since there's no AttachToken() on

a group). Instead, to enable AttachToken() replacement in this case,

create an additional non-dispensable token (node) that's a direct child

of the group and make the existing dispensable token a child of the

additional token (node). This way, the additional token (node) that is

a direct child of the group has BufferCollection.AttachToken() which can

be used to replace the failed dispensable token.

SetDispensable() on an already-dispensable token is idempotent.

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

Most sysmem clients and many participants don't need to care about this

message or about BufferCollectionTokenGroup(s) in general.

A BufferCollectionTokenGroup is used to create a 1 of N OR among N child

tokens. The child tokens which are not selected during aggregation will

fail (close), which a potential participant should notice when their

BufferCollection channel client endpoint sees PEER_CLOSED, allowing the

participant to clean up the speculative usage that didn't end up

happening (similarly to a normal BufferCollection server end closing

on failure of a logical buffer collection).

See comments on protocol BufferCollectionTokenGroup.

Any rights_attenuation_mask or AttachToken()/SetDispensable() to be

applied to the whole group can be achieved with a token for this purpose

as a direct parent of the group.

group_request - the server end of a BufferCollectionTokenGroup channel

to be served by sysmem.

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