#include <channel.h>

Inheritance diagram for pw::channel::AnyChannel:

Public Member Functions
constexpr DataType	data_type () const
	Returns the data type of the channel implementation.

constexpr bool	reliable () const
	Returns whether the channel implementation is reliable.

constexpr bool	seekable () const
	Returns whether the channel implementation is seekable.

constexpr bool	readable () const
	Returns whether the channel implementation is readable.

constexpr bool	writable () const
	Returns whether the channel implementation is writable.

constexpr bool	is_read_open () const

constexpr bool	is_write_open () const

constexpr bool	is_read_or_write_open () const
	True if the channel is open for either reading or writing.

async2::Poll< Result< multibuf::MultiBuf > >	PendRead (async2::Context &cx)

async2::Poll< Status >	PendReadyToWrite (pw::async2::Context &cx)

async2::Poll< std::optional< multibuf::MultiBuf > >	PendAllocateWriteBuffer (async2::Context &cx, size_t min_bytes)

Status	StageWrite (multibuf::MultiBuf &&data)

async2::Poll< Status >	PendWrite (async2::Context &cx)

Status	Seek (async2::Context &cx, ptrdiff_t position, Whence whence)

size_t	Position () const

async2::Poll< pw::Status >	PendClose (async2::Context &cx)

Protected Member Functions
void	set_read_closed ()

void	set_write_closed ()

Private Member Functions
virtual async2::Poll< Status >	DoPendClose (async2::Context &cx)=0
	TODO: b/323622630 - `Seek` and `Position` are not yet implemented.

Friends
template<DataType , Property... >
class	Channel

template<DataType , Property... >
class	internal::BaseChannelImpl

Detailed Description

A generic data channel that may support reading or writing bytes or datagrams.

Note that this channel should be used from only one pw::async::Task at a time, as the Pend methods are only required to remember the latest pw::async2::Context that was provided. Notably, this means that it is not possible to read from the channel in one task while writing to it from another task: a single task must own and operate the channel. In the future, a wrapper will be offered which will allow the channel to be split into a read half and a write half which can be used from independent tasks.

To implement a Channel, inherit from ChannelImpl with the specified properties.

Member Function Documentation

◆ is_read_open()

constexpr bool pw::channel::AnyChannel::is_read_open ( ) const

inlineconstexpr

True if the channel is open for reading. Always false for write-only channels.

◆ is_write_open()

constexpr bool pw::channel::AnyChannel::is_write_open ( ) const

inlineconstexpr

True if the channel is open for writing. Always false for read-only channels.

◆ PendAllocateWriteBuffer()

async2::Poll< std::optional< multibuf::MultiBuf > > pw::channel::AnyChannel::PendAllocateWriteBuffer	(	async2::Context &	cx,
		size_t	min_bytes
	)

inline

Attempts to allocate a write buffer of at least min_bytes bytes.

On success, returns a MultiBuf of at least min_bytes. This buffer should be filled with data and then passed back into StageWrite. The user may shrink or fragment the MultiBuf during its own usage of the buffer, but the MultiBuf should be restored to its original shape before it is passed to StageWrite.

Users should not wait on the result of PendAllocateWriteBuffer while holding an existing MultiBuf from PendAllocateWriteBuffer, as this can result in deadlocks.

This method will return:

Ready(buffer) - A buffer of the requested size is provided.
Ready(std::nullopt) - min_bytes is larger than the maximum buffer size this channel can allocate.
Pending - No buffer of at least min_bytes is available. The task associated with the provided pw::async2::Context will be awoken when a sufficiently-sized buffer becomes available.

◆ PendClose()

async2::Poll< pw::Status > pw::channel::AnyChannel::PendClose ( async2::Context & cx )

inline

Closes the channel, flushing any data.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The channel was closed and all data was sent successfully.
* 
*     DATA_LOSS: The channel was closed, but not all previously written
*     data was delivered.
* 
*     FAILED_PRECONDITION: Channel was already closed, which can happen
*     out-of-band due to errors.
* 
*

◆ PendRead()

async2::Poll< Result< multibuf::MultiBuf > > pw::channel::AnyChannel::PendRead ( async2::Context & cx )

inline

Returns a pw::multibuf::MultiBuf with read data, if available. If data is not available, invokes cx.waker() when it becomes available.

For datagram channels, each successful read yields one complete datagram, which may contain zero or more bytes. For byte stream channels, each successful read yields one or more bytes.

Channels only support one read operation / waker at a time.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Data was read into a MultiBuf.
* 
*     UNIMPLEMENTED: The channel does not support reading.
* 
*     FAILED_PRECONDITION: The channel is closed.
* 
*     OUT_OF_RANGE: The end of the stream was reached. This may be though
*     of as reaching the end of a file. Future reads may succeed after
*     ``Seek`` ing backwards, but no more new data will be produced. The
*     channel is still open; writes and seeks may succeed.
* 
*

◆ PendReadyToWrite()

async2::Poll< Status > pw::channel::AnyChannel::PendReadyToWrite ( pw::async2::Context & cx )

inline

Checks whether a writeable channel is currently writeable.

This should be called before attempting to Write, and may be called before allocating a write buffer if trying to reduce memory pressure.

This method will return:

Ready(OK) - The channel is currently writeable, and a single caller may proceed to Write.
Ready(UNIMPLEMENTED) - The channel does not support writing.
Ready(FAILED_PRECONDITION) - The channel is closed for writing.
Pending - cx will be awoken when the channel becomes writeable again.

Note: this method will always return Ready for non-writeable channels.

◆ PendWrite()

async2::Poll< Status > pw::channel::AnyChannel::PendWrite ( async2::Context & cx )

inline

Completes pending writes.

Returns a async2::Poll indicating whether or the write has completed.

Ready(OK) - All data has been successfully written.
Ready(UNIMPLEMENTED) - The channel does not support writing.
Ready(FAILED_PRECONDITION) - The channel is closed.
Pending - Writing is not complete.

◆ Position()

size_t pw::channel::AnyChannel::Position ( ) const

Returns the current position in the stream, or kUnknownPosition if unsupported.

TODO: b/323622630 - Seek and Position are not yet implemented.

◆ Seek()

Status pw::channel::AnyChannel::Seek	(	async2::Context &	cx,
		ptrdiff_t	position,
		Whence	whence
	)

Seek changes the position in the stream.

TODO: b/323622630 - Seek and Position are not yet implemented.

Any PendRead or Write calls following a call to Seek will be relative to the new position. Already-written data still being flushed will be output relative to the old position.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The current position was successfully changed.
* 
*     UNIMPLEMENTED: The channel does not support seeking.
* 
*     FAILED_PRECONDITION: The channel is closed.
* 
*     NOT_FOUND: The seek was to a valid position, but the channel is no
*     longer capable of seeking to this position (partially seekable
*     channels only).
* 
*     OUT_OF_RANGE: The seek went beyond the end of the stream.
* 
*

◆ StageWrite()

Status pw::channel::AnyChannel::StageWrite ( multibuf::MultiBuf && data )

inline

Writes using a previously allocated MultiBuf. Returns a token that refers to this write. These tokens are monotonically increasing, and PendWrite() returns the value of the latest token it has flushed.

The MultiBuf argument to Write may consist of either: (1) A single MultiBuf allocated by PendAllocateWriteBuffer that has not been combined with any other MultiBuf s or Chunks OR (2) A MultiBuf containing any combination of buffers from sources other than PendAllocateWriteBuffer.

This requirement allows for more efficient use of memory in case (1). For example, a ring-buffer implementation of a Channel may specialize PendAllocateWriteBuffer to return the next section of the buffer available for writing.

Returns

embed:rst:leading-asterisk
 
*  May fail with the following error codes:
* 
*  .. pw-status-codes::
* 
*     OK: Data was accepted by the channel.
* 
*     UNIMPLEMENTED: The channel does not support writing.
* 
*     UNAVAILABLE: The write failed due to a transient error (only applies
*     to unreliable channels).
* 
*     FAILED_PRECONDITION: The channel is closed.
* 
*

The documentation for this class was generated from the following file:

pw_channel/public/pw_channel/channel.h

Public Member Functions

Protected Member Functions

Private Member Functions

Friends

Detailed Description

Member Function Documentation

◆ is_read_open()

◆ is_write_open()

◆ PendAllocateWriteBuffer()

◆ PendClose()

◆ PendRead()

◆ PendReadyToWrite()

◆ PendWrite()

◆ Position()

◆ Seek()

◆ StageWrite()