class WireWeakOnewayBufferClientImpl

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.

Caller provides the backing storage for FIDL message.

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.

Caller provides the backing storage for FIDL message.

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.

Caller provides the backing storage for FIDL message.

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.

Caller provides the backing storage for FIDL message.

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.

Caller provides the backing storage for FIDL message.

Create a child token. Before passing the client end of this token to

BindSharedCollection(), completion of Sync() after CreateChild() is

required. Or the client can use CreateChildrenSync() which essentially

includes the Sync().

token_request - the server end of the new token channel.

rights_attenuation_mask - If ZX_RIGHT_SAME_RIGHTS, the created token

allows the holder to get the same rights to buffers as the parent token

(of the group) had.

Caller provides the backing storage for FIDL message.

AllChildrenPresent()

After creating all children, the client must call AllChildrenPresent()

to inform sysmem that no more children will be created, so that sysmem

can know when it's ok to start aggregating constraints.

If Close() is to be sent, it should be sent _after_

AllChildrenPresent(), else failure of the group and propagation of the

failure to the group's parent will still be triggered.

Caller provides the backing storage for FIDL message.