C/C++ API Reference
Loading...
Searching...
No Matches
pw_channel

Oveview

Async, zero-copy API for sending and receiving bytes or datagrams. Main docs: https://pigweed.dev/pw_channel.

Submodules

 Forwarding
 
 Loopback
 
 Packets
 
 RP2 stdio
 
 Stream channel
 
 epoll
 

Classes

class  pw::channel::Channel< kDataType, kProperties >
 
class  pw::channel::AnyChannel
 
class  pw::channel::ChannelImpl< kDataType, kProperties >
 
class  pw::channel::Implement< ChannelType >
 
class  pw::channel::internal::ForwardingChannel< kType >
 
class  pw::channel::internal::ForwardingChannel< DataType::kDatagram >
 
class  pw::channel::internal::ForwardingChannel< DataType::kByte >
 
class  pw::channel::LoopbackChannel< DataType::kDatagram >
 
class  pw::channel::LoopbackChannel< DataType::kByte >
 
class  pw::channel::PendingWrite< Packet >
 
class  pw::channel::Implement< PacketChannel< Packet, kProperties... > >
 
class  pw::channel::internal::BasePacketChannelImpl< Packet, kProperties >
 
class  pw::channel::internal::PacketChannelImpl< Packet, kProperties >
 
class  pw::channel::internal::PacketChannelImpl< Packet, kReadable >
 
class  pw::channel::internal::PacketChannelImpl< Packet, kWritable >
 
class  pw::channel::internal::PacketChannelImpl< Packet, kReadable, kWritable >
 
class  pw::channel::internal::StreamChannelReadState
 State for the stream-reading thread. More...
 
class  pw::channel::internal::StreamChannelWriteState
 State for the stream-writing thread. More...
 
class  pw::channel::TestPacketReaderWriter< Packet >
 pw::channel::PacketReadWriter implementation for testing use. More...
 

Typedefs

template<Property... kProperties>
using pw::channel::ByteChannel = Channel< DataType::kByte, kProperties... >
 A ByteChannel exchanges data as a stream of bytes.
 
template<Property... kProperties>
using pw::channel::DatagramChannel = Channel< DataType::kDatagram, kProperties... >
 A DatagramChannel exchanges data as a series of datagrams.
 
using pw::channel::ByteReader = ByteChannel< kReadable >
 Unreliable byte-oriented Channel that supports reading.
 
using pw::channel::ByteWriter = ByteChannel< kWritable >
 Unreliable byte-oriented Channel that supports writing.
 
using pw::channel::ByteReaderWriter = ByteChannel< kReadable, kWritable >
 Unreliable byte-oriented Channel that supports reading and writing.
 
using pw::channel::ReliableByteReader = ByteChannel< kReliable, kReadable >
 Reliable byte-oriented Channel that supports reading.
 
using pw::channel::ReliableByteWriter = ByteChannel< kReliable, kWritable >
 Reliable byte-oriented Channel that supports writing.
 
using pw::channel::ReliableByteReaderWriter = ByteChannel< kReliable, kReadable, kWritable >
 Reliable byte-oriented Channel that supports reading and writing.
 
using pw::channel::DatagramReader = DatagramChannel< kReadable >
 Unreliable datagram-oriented Channel that supports reading.
 
using pw::channel::DatagramWriter = DatagramChannel< kWritable >
 Unreliable datagram-oriented Channel that supports writing.
 
using pw::channel::DatagramReaderWriter = DatagramChannel< kReadable, kWritable >
 Unreliable datagram-oriented Channel that supports reading and writing.
 
using pw::channel::ReliableDatagramReader = DatagramChannel< kReliable, kReadable >
 Reliable datagram-oriented Channel that supports reading.
 
using pw::channel::ReliableDatagramWriter = DatagramChannel< kReliable, kWritable >
 Reliable datagram-oriented Channel that supports writing.
 
using pw::channel::ReliableDatagramReaderWriter = DatagramChannel< kReliable, kReadable, kWritable >
 Reliable datagram-oriented Channel that supports reading and writing.
 
template<Property... kProperties>
using pw::channel::ByteChannelImpl = ChannelImpl< DataType::kByte, kProperties... >
 Implement a byte-oriented Channel with the specified properties.
 
template<Property... kProperties>
using pw::channel::DatagramChannelImpl = ChannelImpl< DataType::kDatagram, kProperties... >
 Implement a datagram-oriented Channel with the specified properties.
 
using pw::channel::PacketChannel< T, kProperties >::Packet = T
 
using pw::channel::AnyPacketChannel< T >::Packet = T
 
using pw::channel::internal::BasePacketChannelImpl< Packet, kProperties >::Channel = PacketChannel< Packet, kProperties... >
 

Functions

 pw::channel::EpollChannel::EpollChannel (int channel_fd, async2::Dispatcher &dispatcher, multibuf::MultiBufAllocator &allocator)
 
 pw::channel::EpollChannel::EpollChannel (const EpollChannel &)=delete
 
EpollChannelpw::channel::EpollChannel::operator= (const EpollChannel &)=delete
 
 pw::channel::EpollChannel::EpollChannel (EpollChannel &&)=default
 
EpollChannelpw::channel::EpollChannel::operator= (EpollChannel &&)=default
 
constexpr pw::channel::ForwardingChannelPair< kType >::ForwardingChannelPair (multibuf::MultiBufAllocator &first_write_alloc, multibuf::MultiBufAllocator &second_write_alloc)
 
 pw::channel::ForwardingChannelPair< kType >::ForwardingChannelPair (const ForwardingChannelPair &)=delete
 
ForwardingChannelPairpw::channel::ForwardingChannelPair< kType >::operator= (const ForwardingChannelPair &)=delete
 
 pw::channel::ForwardingChannelPair< kType >::ForwardingChannelPair (ForwardingChannelPair &&)=delete
 
ForwardingChannelPairpw::channel::ForwardingChannelPair< kType >::operator= (ForwardingChannelPair &&)=delete
 
Channel< kType, kReliable, kReadable, kWritable > & pw::channel::ForwardingChannelPair< kType >::first ()
 Returns the first channel in the pair.
 
const Channel< kType, kReliable, kReadable, kWritable > & pw::channel::ForwardingChannelPair< kType >::first () const
 Returns a const reference to the first channel in the pair.
 
Channel< kType, kReliable, kReadable, kWritable > & pw::channel::ForwardingChannelPair< kType >::second ()
 Returns the second channel in the pair.
 
const Channel< kType, kReliable, kReadable, kWritable > & pw::channel::ForwardingChannelPair< kType >::second () const
 Returns a const reference to the second channel in the pair.
 
 pw::channel::internal::ForwardingChannel< DataType::kDatagram >::ForwardingChannel (const ForwardingChannel &)=delete
 
ForwardingChannelpw::channel::internal::ForwardingChannel< DataType::kDatagram >::operator= (const ForwardingChannel &)=delete
 
 pw::channel::internal::ForwardingChannel< DataType::kDatagram >::ForwardingChannel (ForwardingChannel &&)=delete
 
ForwardingChannelpw::channel::internal::ForwardingChannel< DataType::kDatagram >::operator= (ForwardingChannel &&)=delete
 
 pw::channel::internal::ForwardingChannel< DataType::kByte >::ForwardingChannel (const ForwardingChannel &)=delete
 
ForwardingChannelpw::channel::internal::ForwardingChannel< DataType::kByte >::operator= (const ForwardingChannel &)=delete
 
 pw::channel::internal::ForwardingChannel< DataType::kByte >::ForwardingChannel (ForwardingChannel &&)=delete
 
ForwardingChannelpw::channel::internal::ForwardingChannel< DataType::kByte >::operator= (ForwardingChannel &&)=delete
 
 pw::channel::LoopbackChannel< DataType::kDatagram >::LoopbackChannel (multibuf::MultiBufAllocator &write_allocator)
 
 pw::channel::LoopbackChannel< DataType::kDatagram >::LoopbackChannel (const LoopbackChannel &)=delete
 
LoopbackChannelpw::channel::LoopbackChannel< DataType::kDatagram >::operator= (const LoopbackChannel &)=delete
 
 pw::channel::LoopbackChannel< DataType::kDatagram >::LoopbackChannel (LoopbackChannel &&)=default
 
LoopbackChannelpw::channel::LoopbackChannel< DataType::kDatagram >::operator= (LoopbackChannel &&)=default
 
 pw::channel::LoopbackChannel< DataType::kByte >::LoopbackChannel (multibuf::MultiBufAllocator &write_allocator)
 
 pw::channel::LoopbackChannel< DataType::kByte >::LoopbackChannel (const LoopbackChannel &)=delete
 
LoopbackChannelpw::channel::LoopbackChannel< DataType::kByte >::operator= (const LoopbackChannel &)=delete
 
 pw::channel::LoopbackChannel< DataType::kByte >::LoopbackChannel (LoopbackChannel &&)=default
 
LoopbackChannelpw::channel::LoopbackChannel< DataType::kByte >::operator= (LoopbackChannel &&)=default
 
 pw::channel::PendingWrite< Packet >::PendingWrite (const PendingWrite &)=delete
 
PendingWritepw::channel::PendingWrite< Packet >::operator= (const PendingWrite &)=delete
 
constexpr pw::channel::PendingWrite< Packet >::PendingWrite (PendingWrite &&other)
 
constexpr PendingWritepw::channel::PendingWrite< Packet >::operator= (PendingWrite &&other)
 
void pw::channel::PendingWrite< Packet >::Stage (Packet &&packet)
 
size_t pw::channel::PendingWrite< Packet >::num_packets () const
 
static constexpr bool pw::channel::PacketChannel< T, kProperties >::readable ()
 
static constexpr bool pw::channel::PacketChannel< T, kProperties >::writable ()
 
constexpr bool pw::channel::PacketChannel< T, kProperties >::is_read_open () const
 
constexpr bool pw::channel::PacketChannel< T, kProperties >::is_write_open () const
 
constexpr bool pw::channel::PacketChannel< T, kProperties >::is_read_or_write_open () const
 
async2::PollResult< Packet > pw::channel::PacketChannel< T, kProperties >::PendRead (async2::Context &cx)
 
async2::PollResult< PendingWrite< Packet > > pw::channel::PacketChannel< T, kProperties >::PendReadyToWrite (async2::Context &cx, size_t num=1)
 
async2::Poll pw::channel::PacketChannel< T, kProperties >::PendWrite (async2::Context &cx)
 
void pw::channel::PacketChannel< T, kProperties >::SetAvailableWrites (uint16_t available_writes)
 
void pw::channel::PacketChannel< T, kProperties >::AcknowledgeWrites (uint16_t num_completed)
 
async2::Poll< Statuspw::channel::PacketChannel< T, kProperties >::PendClose (async2::Context &cx)
 
template<typename Sibling , typename = internal::EnableIfConvertible<PacketChannel, Sibling>>
constexpr pw::channel::PacketChannel< T, kProperties >::operator Sibling & ()
 Channels may be implicitly converted to other compatible channel types.
 
template<typename Sibling , typename = internal::EnableIfConvertible<PacketChannel, Sibling>>
constexpr pw::channel::PacketChannel< T, kProperties >::operator const Sibling & () const
 
constexpr pw::channel::PacketChannel< T, kProperties >::operator AnyPacketChannel< Packet > & ()
 
constexpr pw::channel::PacketChannel< T, kProperties >::operator const AnyPacketChannel< Packet > & () const
 
template<typename Sibling >
Sibling & pw::channel::PacketChannel< T, kProperties >::as ()
 Returns a reference to this as another compatible packet channel type.
 
template<typename Sibling >
const Sibling & pw::channel::PacketChannel< T, kProperties >::as () const
 
uint16_t pw::channel::PacketChannel< T, kProperties >::GetAvailableWrites () const
 
constexpr bool pw::channel::AnyPacketChannel< T >::readable () const
 Returns whether the channel implementation is readable.
 
constexpr bool pw::channel::AnyPacketChannel< T >::writable () const
 Returns whether the channel implementation is writable.
 
constexpr bool pw::channel::AnyPacketChannel< T >::is_read_open () const
 
constexpr bool pw::channel::AnyPacketChannel< T >::is_write_open () const
 
constexpr bool pw::channel::AnyPacketChannel< T >::is_read_or_write_open () const
 True if the channel is open for either reading or writing.
 
async2::PollResult< Packet > pw::channel::AnyPacketChannel< T >::PendRead (async2::Context &cx)
 
async2::PollResult< PendingWrite< Packet > > pw::channel::AnyPacketChannel< T >::PendReadyToWrite (async2::Context &cx, size_t num=1)
 
async2::Poll pw::channel::AnyPacketChannel< T >::PendWrite (async2::Context &cx)
 
void pw::channel::AnyPacketChannel< T >::SetAvailableWrites (uint16_t available_writes)
 
void pw::channel::AnyPacketChannel< T >::AcknowledgeWrites (uint16_t num_completed)
 
async2::Poll< Statuspw::channel::AnyPacketChannel< T >::PendClose (async2::Context &cx)
 
uint16_t pw::channel::AnyPacketChannel< T >::GetAvailableWrites () const
 
void pw::channel::AnyPacketChannel< T >::set_read_closed ()
 
void pw::channel::AnyPacketChannel< T >::set_write_closed ()
 
void pw::channel::AnyPacketChannel< T >::set_read_write_closed ()
 
async2::Wakerpw::channel::AnyPacketChannel< T >::write_waker ()
 Allows implementations to access the write waker.
 
Channelpw::channel::internal::BasePacketChannelImpl< Packet, kProperties >::channel ()
 
const Channelpw::channel::internal::BasePacketChannelImpl< Packet, kProperties >::channel () const
 
 pw::channel::internal::StreamChannelReadState::StreamChannelReadState (const StreamChannelReadState &)=delete
 
StreamChannelReadStatepw::channel::internal::StreamChannelReadState::operator= (const StreamChannelReadState &)=delete
 
 pw::channel::internal::StreamChannelReadState::StreamChannelReadState (StreamChannelReadState &&)=delete
 
StreamChannelReadStatepw::channel::internal::StreamChannelReadState::operator= (StreamChannelReadState &&)=delete
 
bool pw::channel::internal::StreamChannelReadState::HasBufferToFill ()
 
void pw::channel::internal::StreamChannelReadState::ProvideBufferToFill (multibuf::MultiBuf &&buf)
 Provide a buffer for ReadLoop to read data into.
 
async2::PollResult< multibuf::MultiBufpw::channel::internal::StreamChannelReadState::PendFilledBuffer (async2::Context &cx)
 
void pw::channel::internal::StreamChannelReadState::ReadLoop (stream::Reader &reader)
 
 pw::channel::internal::StreamChannelWriteState::StreamChannelWriteState (const StreamChannelWriteState &)=delete
 
StreamChannelWriteStatepw::channel::internal::StreamChannelWriteState::operator= (const StreamChannelWriteState &)=delete
 
 pw::channel::internal::StreamChannelWriteState::StreamChannelWriteState (StreamChannelWriteState &&)=delete
 
StreamChannelWriteStatepw::channel::internal::StreamChannelWriteState::operator= (StreamChannelWriteState &&)=delete
 
Status pw::channel::internal::StreamChannelWriteState::SendData (multibuf::MultiBuf &&buf)
 
void pw::channel::internal::StreamChannelWriteState::WriteLoop (stream::Writer &writer)
 
 pw::channel::StreamChannel::StreamChannel (stream::Reader &reader, const thread::Options &read_thread_options, multibuf::MultiBufAllocator &read_allocator, stream::Writer &writer, const thread::Options &write_thread_option, multibuf::MultiBufAllocator &write_allocator)
 
 pw::channel::StreamChannel::StreamChannel (multibuf::MultiBufAllocator &allocator, stream::Reader &reader, const thread::Options &read_thread_options, stream::Writer &writer, const thread::Options &write_thread_options)
 
 pw::channel::StreamChannel::StreamChannel (const StreamChannel &)=delete
 
StreamChannelpw::channel::StreamChannel::operator= (const StreamChannel &)=delete
 
 pw::channel::StreamChannel::StreamChannel (StreamChannel &&)=delete
 
StreamChannelpw::channel::StreamChannel::operator= (StreamChannel &&)=delete
 
constexpr pw::channel::TestPacketReaderWriter< Packet >::TestPacketReaderWriter (allocator::Allocator &allocator)
 
span< const Packet > pw::channel::TestPacketReaderWriter< Packet >::written_packets () const
 Returns all packets that have been written to this packet channel.
 
void pw::channel::TestPacketReaderWriter< Packet >::EnqueueReadPacket (Packet &&packet)
 Enqueues packets to be returned from future PendRead calls.
 

Friends

template<DataType >
class pw::channel::ForwardingChannelPair< kType >::internal::ForwardingChannel
 
class pw::channel::internal::ForwardingChannel< DataType::kDatagram >::ForwardingChannelPair< DataType::kDatagram >
 
class pw::channel::internal::ForwardingChannel< DataType::kByte >::ForwardingChannelPair< DataType::kByte >
 
class pw::channel::PendingWrite< Packet >::AnyPacketChannel< Packet >
 
template<typename >
class pw::channel::PacketChannel< T, kProperties >::AnyPacketChannel
 
template<typename , Property... >
class pw::channel::AnyPacketChannel< T >::PacketChannel
 
template<typename , Property... >
class pw::channel::AnyPacketChannel< T >::internal::BasePacketChannelImpl
 
class pw::channel::internal::BasePacketChannelImpl< Packet, kProperties >::PacketChannelImpl< Packet, kProperties... >
 
class pw::NoDestructor< StreamChannel >
 

Function Documentation

◆ AcknowledgeWrites()

template<typename Packet >
void pw::channel::AnyPacketChannel< Packet >::AcknowledgeWrites ( uint16_t  num_completed)

Increases the number of available writes and wakes. Equivalent to SetAvailableWrites(GetAvailableWrites() + num_completed). Wakes a task waiting for PendReadyToWrite, if any.

Crashes if GetAvailableWrites() is kNoFlowControl.

◆ DoPendRead()

template<typename Packet >
async2::PollResult< Packet > pw::channel::internal::PacketChannelImpl< Packet, kWritable >::DoPendRead ( async2::Context )
inlinefinalprivatevirtual

◆ DoPendReadyToWrite()

template<typename Packet >
async2::Poll< Status > pw::channel::internal::PacketChannelImpl< Packet, kReadable >::DoPendReadyToWrite ( async2::Context ,
size_t   
)
inlinefinalprivatevirtual

◆ DoPendWrite()

template<typename Packet >
async2::Poll pw::channel::internal::PacketChannelImpl< Packet, kReadable >::DoPendWrite ( async2::Context )
inlinefinalprivatevirtual

◆ DoStageWrite()

template<typename Packet >
void pw::channel::internal::PacketChannelImpl< Packet, kReadable >::DoStageWrite ( Packet &&  )
inlinefinalprivatevirtual

◆ GetAvailableWrites()

template<typename T >
uint16_t pw::channel::AnyPacketChannel< T >::GetAvailableWrites ( ) const
inlineprotected

Indicates how many additional packets can currently be sent to the remote receiver.

◆ HasBufferToFill()

bool pw::channel::internal::StreamChannelReadState::HasBufferToFill ( )

Whether or not the ReadLoop already has a buffer available into which data can be read.

◆ is_read_open()

template<typename T >
constexpr bool pw::channel::AnyPacketChannel< T >::is_read_open ( ) const
inlineconstexpr

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

◆ is_write_open()

template<typename T >
constexpr bool pw::channel::AnyPacketChannel< T >::is_write_open ( ) const
inlineconstexpr

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

◆ PendClose()

template<typename Packet >
async2::Poll< Status > pw::channel::AnyPacketChannel< Packet >::PendClose ( async2::Context cx)

Marks the channel as closed. Flushes any remaining 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.
* 
*  

◆ PendFilledBuffer()

async2::PollResult< multibuf::MultiBuf > pw::channel::internal::StreamChannelReadState::PendFilledBuffer ( async2::Context cx)

Receives any available data processed by ReadLoop.

If no data is available, schedules a wakeup of the task in cx when new data arrives.

◆ PendRead()

template<typename T >
async2::PollResult< Packet > pw::channel::AnyPacketChannel< T >::PendRead ( async2::Context cx)
inline

Returns async2::Ready with a new packet when one arrives. If no packet is ready yet, returns async2::Pending. Returns async2::Ready with a non-OK status if there was an unrecoverable error.

Returns
embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: A packet was read
* 
*     UNIMPLEMENTED: The channel does not support reading.
* 
*     FAILED_PRECONDITION: The channel is closed for reading.
* 
*     OUT_OF_RANGE: The end of the stream was reached and no further reads
*     will succeed.
* 
*  

◆ PendReadyToWrite()

template<typename Packet >
async2::PollResult< PendingWrite< Packet > > pw::channel::AnyPacketChannel< Packet >::PendReadyToWrite ( async2::Context cx,
size_t  num = 1 
)

Returns async2::Ready if num packets can currently be staged, and async2::Pending otherwise. Returns async2::Ready with a non-OK status if there was an unrecoverable error.

TODO: b/421961717 - Determine whether to keep this method.

Returns
embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The channel is currently writable. The returned `PendingWrite` may
*     be used to write a packet.
* 
*     UNIMPLEMENTED: The channel does not support writing.
* 
*     FAILED_PRECONDITION: The channel is closed for writing.
* 
*  

◆ PendWrite()

template<typename Packet >
async2::Poll pw::channel::AnyPacketChannel< Packet >::PendWrite ( async2::Context cx)

Processes staged write packets. PendWrite must be called after a write is staged so the channel can complete the write. This could involve writing to physical hardware, pushing data into a queue, or be a no-op.

PendReadyToWrite also allows the channel to send staged packets, but it is only called when there is a new outbound packet. PendWrite should be called after a write to avoid blocking outbound data until there is another packet to write.

If the packets have a deallocator set, they will be automatically deallocated after they are written.

Returns
async2::Ready when the channel has completed the write operation for all outbound data. Returns async2::Pending otherwise.

◆ ReadLoop()

void pw::channel::internal::StreamChannelReadState::ReadLoop ( stream::Reader reader)

A loop which reads data from reader into buffers provided by ProvideBufferToFill and then makes them available via PendFilledBuffer.

This is blocking and is intended to be run on an independent thread.

◆ SendData()

Status pw::channel::internal::StreamChannelWriteState::SendData ( multibuf::MultiBuf &&  buf)

Queues buf to be sent into writer via the WriteLoop.

Returns a status indicating whether the WriteLoop has encountered errors writing into writer.

◆ set_read_closed()

template<typename T >
void pw::channel::AnyPacketChannel< T >::set_read_closed ( )
inlineprotected

Marks the channel as closed for reading, but does nothing else.

PendClose() always marks the channel closed when DoPendClose() returns Ready(), regardless of the status.

◆ set_read_write_closed()

template<typename T >
void pw::channel::AnyPacketChannel< T >::set_read_write_closed ( )
inlineprotected

Marks the channel as close for both reading and writing, but does nothing else.

PendClose() always marks the channel closed when DoPendClose() returns Ready(), regardless of the status.

◆ set_write_closed()

template<typename T >
void pw::channel::AnyPacketChannel< T >::set_write_closed ( )
inlineprotected

Marks the channel as closed for writing, but does nothing else.

PendClose() always marks the channel closed when DoPendClose() returns Ready(), regardless of the status.

◆ SetAvailableWrites()

template<typename Packet >
void pw::channel::AnyPacketChannel< Packet >::SetAvailableWrites ( uint16_t  available_writes)

Sets the number of packets the remote receiver can currently receive. This is typically set based on information from the receiver. Wakes any task waiting for PendReadyToWrite if the number of available writes increased.

Set available_writes to kNoFlowControl to disable flow control and wake any pending task.

◆ Stage()

template<typename Packet >
void pw::channel::PendingWrite< Packet >::Stage ( Packet &&  packet)
inline

Enqueues a packet to be written. Must be called before the PendingWrite goes out of scope.

Stage may be called up to num_packets() times.

◆ WriteLoop()

void pw::channel::internal::StreamChannelWriteState::WriteLoop ( stream::Writer writer)

A loop which writes the data sent via SendData into writer.

This is blocking and is intended to be run on an independent thread.