class WireWeakOnewayBufferClientImpl

###### On a [`fuchsia.sysmem2/BufferCollectionToken`] channel:

Normally a participant will convert a `BufferCollectionToken` into a

[`fuchsia.sysmem2/BufferCollection`], but a participant can instead send

`Release` via the token (and then close the channel immediately or

shortly later in response to server closing the server end), which

avoids causing buffer collection failure. Without a prior `Release`,

closing the `BufferCollectionToken` client end will cause buffer

collection failure.

###### On a [`fuchsia.sysmem2/BufferCollection`] channel:

By default the server handles unexpected closure of a

[`fuchsia.sysmem2/BufferCollection`] client end (without `Release`

first) by failing the 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` without

causing buffer collection failure, the participant can send `Release`

before closing the `BufferCollection` client end. The `Release` 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, despite the lack of `BufferCollection` connection at the

time of constraints aggregation.

###### On a [`fuchsia.sysmem2/BufferCollectionTokenGroup`] channel:

By default, unexpected closure of a `BufferCollectionTokenGroup` client

end (without `Release` first) will trigger failure of the buffer

collection. To close a `BufferCollectionTokenGroup` channel without

failing the buffer collection, ensure that AllChildrenPresent() has been

sent, and send `Release` before closing the `BufferCollectionTokenGroup`

client end.

If `Release` occurs before

[`fuchsia.sysmem2/BufferCollectionTokenGroup.AllChildrenPresent], the

buffer collection will fail (triggered by reception of `Release` without

prior `AllChildrenPresent`). This is intentionally not analogous to how

[`fuchsia.sysmem2/BufferCollection.Release`] without

[`fuchsia.sysmem2/BufferCollection.SetConstraints`] first doesn't cause

buffer collection failure. For a `BufferCollectionTokenGroup`, clean

close requires `AllChildrenPresent` (if not already sent), then

`Release`, then close client end.

If `Release` occurs after `AllChildrenPresent`, the children and all

their constraints remain intact (just as they would if the

`BufferCollectionTokenGroup` channel had remained open), and the client

end close doesn't trigger buffer collection failure.

###### On all [`fuchsia.sysmem2/Node`] channels (any of the above):

For brevity, the per-channel-protocol paragraphs above ignore the

separate failure domain created by

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

[`fuchsia.sysmem2/BufferCollection.AttachToken`]. When a client end

unexpectedly closes (without `Release` first) and that client end is

under a failure domain, instead of failing the whole buffer collection,

the failure domain is failed, but the buffer collection itself is

isolated from failure of the failure domain. Such failure domains can be

nested, in which case only the inner-most failure domain in which the

`Node` resides fails.

Caller provides the backing storage for FIDL message.

Set a name for VMOs in this buffer collection.

If the name doesn't fit in ZX_MAX_NAME_LEN, the name of the vmo itself

will be truncated to fit. The name of the vmo will be suffixed with the

buffer index within the collection (if the suffix fits within

ZX_MAX_NAME_LEN). The name specified here (without truncation) will be

listed in the inspect data.

The name only affects VMOs allocated after the name is set; this call

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

then the larger priority value will win. Setting a new name with the

same priority as a prior name doesn't change the name.

All table fields are currently required.

+ request `priority` The name is only set if this is the first `SetName`

or if `priority` is greater than any previous `priority` value in

prior `SetName` calls across all `Node`(s) of this buffer collection.

+ request `name` The name for VMOs created under this buffer collection.

Caller provides the backing storage for FIDL message.

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 this [`fuchsia.sysmem2/Node`] and all

`Node`(s) derived from this `Node`, unless overriden by

[`fuchsia.sysmem2/Allocator.SetDebugClientInfo`] or a later

[`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`].

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

indicate which client is closing their channel first, leading to subtree

failure (which can be normal if the purpose of the subtree 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).

All table fields are currently required.

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

Caller provides the backing storage for FIDL message.

Sysmem logs a warning if sysmem hasn't seen

[`fuchsia.sysmem2/BufferCollection.SetConstraints`] from all clients

within 5 seconds after creation of a new 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.

In most cases the default works well.

All table fields are currently required.

+ request `deadline` The time at which sysmem will start trying to log

the warning, unless all constraints are with sysmem by then.

Caller provides the backing storage for FIDL message.

This enables verbose logging for the buffer collection.

Verbose logging includes constraints set via

[`fuchsia.sysmem2/BufferCollection.SetConstraints`] from each client

along with info set via [`fuchsia.sysmem2/Node.SetDebugClientInfo`] (or

[`fuchsia.sysmem2/Allocator.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 little surrounding context. While this is often enough to diagnose

a problem if only a small change was made and everything was 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

[`fuchsia.sysmem2/BufferCollection.AttachToken`],

[`fuchsia.sysmem2/BufferCollectionToken.SetDispensable`],

[`fuchsia.sysmem2/BufferCollectionTokenGroup`] nodes, and associated

subtrees 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

subtree is failing sooner than expected.

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

point of view, under the assumption that verbose logging is only enabled

on a low number of buffer collections. If we're not tracking down a bug,

we shouldn't send this message.

Caller provides the backing storage for FIDL message.

Sets the current [`fuchsia.sysmem2/Node`] and all child `Node`(s)

created after this message to weak, which means that a client's `Node`

client end (or a child created after this message) is not alone

sufficient to keep allocated VMOs alive.

All VMOs obtained from weak `Node`(s) are weak sysmem VMOs. See also

`close_weak_asap`.

This message is only permitted before the `Node` becomes ready for

allocation (else the server closes the channel with `ZX_ERR_BAD_STATE`):

* `BufferCollectionToken`: any time

* `BufferCollection`: before `SetConstraints`

* `BufferCollectionTokenGroup`: before `AllChildrenPresent`

Currently, no conversion from strong `Node` to weak `Node` after ready

for allocation is provided, but a client can simulate that by creating

an additional `Node` before allocation and setting that additional

`Node` to weak, and then potentially at some point later sending

`Release` and closing the client end of the client's strong `Node`, but

keeping the client's weak `Node`.

Zero strong `Node`(s) and zero strong VMO handles will result in buffer

collection failure (all `Node` client end(s) will see

`ZX_CHANNEL_PEER_CLOSED` and all `close_weak_asap` `client_end`(s) will

see `ZX_EVENTPAIR_PEER_CLOSED`), but sysmem (intentionally) won't notice

this situation until all `Node`(s) are ready for allocation. For initial

allocation to succeed, at least one strong `Node` is required to exist

at allocation time, but after that client receives VMO handles, that

client can `BufferCollection.Release` and close the client end without

causing this type of failure.

This implies [`fuchsia.sysmem2/Node.SetWeakOk`] as well, but does not

imply `SetWeakOk` with `for_children_also` true, which can be sent

separately as appropriate.

Caller provides the backing storage for FIDL message.

This indicates to sysmem that the client is prepared to pay attention to

`close_weak_asap`.

If sent, this message must be before

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

All participants using a weak [`fuchsia.sysmem2/BufferCollection`] must

send this message before `WaitForAllBuffersAllocated`, or a parent

`Node` must have sent [`fuchsia.sysmem2/Node.SetWeakOk`] with

`for_child_nodes_also` true, else the `WaitForAllBuffersAllocated` will

trigger buffer collection failure.

This message is necessary because weak sysmem VMOs have not always been

a thing, so older clients are not aware of the need to pay attention to

`close_weak_asap` `ZX_EVENTPAIR_PEER_CLOSED` and close all remaining

sysmem weak VMO handles asap. By having this message and requiring

participants to indicate their acceptance of this aspect of the overall

protocol, we avoid situations where an older client is delivered a weak

VMO without any way for sysmem to get that VMO to close quickly later

(and on a per-buffer basis).

A participant that doesn't handle `close_weak_asap` and also doesn't

retrieve any VMO handles via `WaitForAllBuffersAllocated` doesn't need

to send `SetWeakOk` (and doesn't need to have a parent `Node` send

`SetWeakOk` with `for_child_nodes_also` true either). However, if that

same participant has a child/delegate which does retrieve VMOs, that

child/delegate will need to send `SetWeakOk` before

`WaitForAllBuffersAllocated`.

+ request `for_child_nodes_also` If present and true, this means direct

child nodes of this node created after this message plus all

descendants of those nodes will behave as if `SetWeakOk` was sent on

those nodes. Any child node of this node that was created before this

message is not included. This setting is "sticky" in the sense that a

subsequent `SetWeakOk` without this bool set to true does not reset

the server-side bool. If this creates a problem for a participant, a

workaround is to `SetWeakOk` with `for_child_nodes_also` true on child

tokens instead, as appropriate. A participant should only set

`for_child_nodes_also` true if the participant can really promise to

obey `close_weak_asap` both for its own weak VMO handles, and for all

weak VMO handles held by participants holding the corresponding child

`Node`(s). When `for_child_nodes_also` is set, descendent `Node`(s)

which are using sysmem(1) can be weak, despite the clients of those

sysmem1 `Node`(s) not having any direct way to `SetWeakOk` or any

direct way to find out about `close_weak_asap`. This only applies to

descendents of this `Node` which are using sysmem(1), not to this

`Node` when converted directly from a sysmem2 token to a sysmem(1)

token, which will fail allocation unless an ancestor of this `Node`

specified `for_child_nodes_also` true.

Caller provides the backing storage for FIDL message.

The server_end will be closed after this `Node` and any child nodes have

have released their buffer counts, making those counts available for

reservation by a different `Node` via

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

The `Node` buffer counts may not be released until the entire tree of

`Node`(s) is closed or failed, because

[`fuchsia.sysmem2/BufferCollection.Release`] followed by channel close

does not immediately un-reserve the `Node` buffer counts. Instead, the

`Node` buffer counts remain reserved until the orphaned node is later

cleaned up.

If the `Node` exceeds a fairly large number of attached eventpair server

ends, a log message will indicate this and the `Node` (and the

appropriate) sub-tree will fail.

The `server_end` will remain open when

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

[`fuchsia.sysmem2/BufferCollectionToken`] into a

[`fuchsia.sysmem2/BufferCollection`].

This message can also be used with a

[`fuchsia.sysmem2/BufferCollectionTokenGroup`].

Caller provides the backing storage for FIDL message.