pw::channel::Channel< kDataType, kProperties > Class Template Reference

#include <channel.h>

Inheritance diagram for pw::channel::Channel< kDataType, kProperties >:

Public Member Functions
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 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)
async2::Poll< pw::Status >	PendClose (async2::Context &cx)
template<typename Sibling , typename = internal::EnableIfConversionIsValid<Channel, Sibling>>
constexpr	operator Sibling & ()
	Channels may be implicitly converted to other compatible channel types.
template<typename Sibling , typename = internal::EnableIfConversionIsValid<Channel, Sibling>>
constexpr	operator const Sibling & () const
template<typename Sibling >
Sibling &	as ()
	Returns a reference to this channel as another compatible channel type.
template<typename Sibling >
const Sibling &	as () const
template<Property... kOtherChannelProperties>
auto &	as ()
template<Property... kOtherChannelProperties>
const auto &	as () const
Channel< DataType::kByte, kProperties... > &	IgnoreDatagramBoundaries ()
const Channel< DataType::kByte, kProperties... > &	IgnoreDatagramBoundaries () const

Static Public Member Functions
static constexpr DataType	data_type ()
	Returns the data type of this channel.
static constexpr bool	reliable ()
	Returns whether the channel type is reliable.
static constexpr bool	seekable ()
	Returns whether the channel type is seekable.
static constexpr bool	readable ()
	Returns whether the channel type is readable.
static constexpr bool	writable ()
	Returns whether the channel type is writable.

Friends
class	AnyChannel

Detailed Description

template<DataType kDataType, Property... kProperties>
class pw::channel::Channel< kDataType, kProperties >

The basic Channel type. Unlike AnyChannel, the Channel's properties are expressed in template parameters and thus reflected in the type.

Properties must be specified in order (kDatagram, kReliable, kReadable, kWritable, kSeekable) and without duplicates.

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

Member Function Documentation

as()

template<DataType kDataType, Property... kProperties>

template<Property... kOtherChannelProperties>

auto & pw::channel::Channel< kDataType, kProperties >::as ( )

inline

Returns a reference to this channel as another channel with the specified properties, which must be compatible.

is_read_open()

template<DataType kDataType, Property... kProperties>

constexpr bool pw::channel::Channel< kDataType, kProperties >::is_read_open ( ) const

constexpr

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

is_write_open()

template<DataType kDataType, Property... kProperties>

constexpr bool pw::channel::Channel< kDataType, kProperties >::is_write_open ( ) const

constexpr

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

PendAllocateWriteBuffer()

template<DataType kDataType, Property... kProperties>

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

PendClose()

template<DataType kDataType, Property... kProperties>

async2::Poll< pw::Status > pw::channel::Channel< kDataType, kProperties >::PendClose

(

async2::Context &

cx

)

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()

template<DataType kDataType, Property... kProperties>

async2::Poll< Result< multibuf::MultiBuf > > pw::channel::Channel< kDataType, kProperties >::PendRead

(

async2::Context &

cx

)

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()

template<DataType kDataType, Property... kProperties>

async2::Poll< Status > pw::channel::Channel< kDataType, kProperties >::PendReadyToWrite

(

pw::async2::Context &

cx

)

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()

template<DataType kDataType, Property... kProperties>

async2::Poll< Status > pw::channel::Channel< kDataType, kProperties >::PendWrite

(

async2::Context &

cx

)

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.

StageWrite()

template<DataType kDataType, Property... kProperties>

Status pw::channel::Channel< kDataType, kProperties >::StageWrite

(

multibuf::MultiBuf &&

data

)

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