class Channel

Channel cannot be copied.

Channel can be moved. Once moved, invoking a method on an instance will

yield undefined behavior.

Closes the handle, causing the underlying object to be reclaimed by the runtime

if no other handles to it exist.

If there is a pending callback registered via |fdf_channel_wait_async|,

it must be cancelled before this is called. For unsynchronized dispatchers,

cancellation is not considered complete until the callback is invoked.

It is not an error to close the special "never a valid handle" FDF_HANDLE_INVALID,

similar to free(NULL) being a valid call.

Closing the last handle to a peered object using |fdf_handle_close| can affect the

state of the object's peer (if any).

Attempts to write a message to the channel.

The caller retains ownership of the |arena| reference, which must be destroyed via

|fdf_arena_drop_ref|. It is okay to call |fdf_arena_drop_ref| on the arena as soon as

the write call returns, as |fdf_arena_write| will take its own reference to the arena,

extending the lifetime of the arena is until the data is read.

The pointers |data| and |handles| may be NULL if their respective sizes are zero.

|data| and |handles| must be pointers managed by |arena| if they are not NULL.

|handles| may be a mix of zircon handles and fdf handles.

Handles with a pending callback registered via |fdf_channel_wait_async| cannot be transferred.

On success, all |num_handles| of the handles in the handles array are attached to the

message and will become available to the reader of that message from the opposite end of the

channel.

All handles are consumed and are no longer available to the caller, on success or failure.

# Errors

ZX_ERR_INVALID_ARGS: |data| or |handles| are not pointers managed by |arena|,

or any element in |handles| is not a valid handle,

or at least one of |handles| has a pending callback registered via |fdf_channel_wait_async|.

ZX_ERR_NO_MEMORY: Failed due to a lack of memory.

ZX_ERR_PEER_CLOSED: The other side of the channel is closed.

This operation is thread-safe.

Attempts to write a message to the channel.

The caller retains ownership of the |arena| reference, which must be destroyed via

|fdf_arena_drop_ref|. It is okay to call |fdf_arena_drop_ref| on the arena as soon as

the write call returns, as |fdf_arena_write| will take its own reference to the arena,

extending the lifetime of the arena is until the data is read.

The pointers |data| and |handles| may be NULL if their respective sizes are zero.

|data| and |handles| must be pointers managed by |arena| if they are not NULL.

|handles| may be a mix of zircon handles and fdf handles.

Handles with a pending callback registered via |fdf_channel_wait_async| cannot be transferred.

On success, all |num_handles| of the handles in the handles array are attached to the

message and will become available to the reader of that message from the opposite end of the

channel.

All handles are consumed and are no longer available to the caller, on success or failure.

# Errors

ZX_ERR_INVALID_ARGS: |data| or |handles| are not pointers managed by |arena|,

or any element in |handles| is not a valid handle,

or at least one of |handles| has a pending callback registered via |fdf_channel_wait_async|.

ZX_ERR_NO_MEMORY: Failed due to a lack of memory.

ZX_ERR_PEER_CLOSED: The other side of the channel is closed.

This operation is thread-safe.

Attempts to read the first message from the channel and returns a |ReadReturn|.

# Errors

ZX_ERR_SHOULD_WAIT: The channel contained no messages to read.

ZX_ERR_PEER_CLOSED: There are no available messages and the other

side of the channel is closed.

This operation is thread-safe.

Channel::Call() is like a combined Channel::Write(), ChannelRead::Begin(),

and Channel::Call(), with the addition of a feature where a transaction id at

the front of the message payload bytes is used to match reply messages with send messages,

enabling multiple calling threads to share a channel without any additional client-side

bookkeeping.

The first four bytes of the written and read back messages are treated as a

transaction ID of type fdf_txid_t. The runtime generates a txid for the

written message, replacing that part of the message as read from the user.

The runtime generated txid will be between 0x80000000 and 0xFFFFFFFF,

and will not collide with any txid from any other Channel::Call()

in progress against this channel endpoint. If the written message has a

length of fewer than four bytes, an error is reported.

While |deadline| has not passed, if an inbound message arrives with a matching txid,

instead of being added to the tail of the general inbound message queue,

it is delivered directly to the thread waiting in Channel::Call().

If such a reply arrives after |deadline| has passed, it will arrive in the

general inbound message queue.

All written handles are consumed and are no longer available to the caller,

on success or failure.

# Errors

ZX_ERR_INVALID_ARGS: |data| or |handles| are not pointers managed by |arena|,

are not managed by |arena|, or element in |handles| is not a valid handle,

or |num_bytes| is less than four,

or at least one of |handles| has a pending callback registered via a ChannelRead.

ZX_ERR_PEER_CLOSED: The other side of the channel is closed.

ZX_ERR_TIMED_OUT: |deadline| passed before a reply matching

the correct txid was received.

ZX_ERR_BAD_STATE: This is called from a driver runtime managed thread

that does not allow sync calls.

This operation is thread-safe.

Channel::Call() is like a combined Channel::Write(), ChannelRead::Begin(),

and Channel::Call(), with the addition of a feature where a transaction id at

the front of the message payload bytes is used to match reply messages with send messages,

enabling multiple calling threads to share a channel without any additional client-side

bookkeeping.

The first four bytes of the written and read back messages are treated as a

transaction ID of type fdf_txid_t. The runtime generates a txid for the

written message, replacing that part of the message as read from the user.

The runtime generated txid will be between 0x80000000 and 0xFFFFFFFF,

and will not collide with any txid from any other Channel::Call()

in progress against this channel endpoint. If the written message has a

length of fewer than four bytes, an error is reported.

While |deadline| has not passed, if an inbound message arrives with a matching txid,

instead of being added to the tail of the general inbound message queue,

it is delivered directly to the thread waiting in Channel::Call().

If such a reply arrives after |deadline| has passed, it will arrive in the

general inbound message queue.

All written handles are consumed and are no longer available to the caller,

on success or failure.

# Errors

ZX_ERR_INVALID_ARGS: |data| or |handles| are not pointers managed by |arena|,

are not managed by |arena|, or element in |handles| is not a valid handle,

or |num_bytes| is less than four,

or at least one of |handles| has a pending callback registered via a ChannelRead.

ZX_ERR_PEER_CLOSED: The other side of the channel is closed.

ZX_ERR_TIMED_OUT: |deadline| passed before a reply matching

the correct txid was received.

ZX_ERR_BAD_STATE: This is called from a driver runtime managed thread

that does not allow sync calls.

This operation is thread-safe.