C/C++ API Reference
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Friends | List of all members
pw::channel::Channel< kDataType, kProperties > Class Template Reference
pw_channel

Overview

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.

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

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::PollResult< multibuf::MultiBuf > PendRead (async2::Context &cx)
 
async2::Poll< Status > PendReadyToWrite (pw::async2::Context &cx)
 
async2::PollOptional< 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
 

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.

◆ IgnoreDatagramBoundaries()

template<DataType kDataType, Property... kProperties>
Channel< DataType::kByte, kProperties... > & pw::channel::Channel< kDataType, kProperties >::IgnoreDatagramBoundaries ( )
inline
Returns
A byte channel reference to a datagram channel

◆ 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::PollOptional< 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
  • 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::PollResult< 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
  • 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 thought of as reaching the end of a file. Future reads may succeed after seeking 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
May fail with the following error 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: