pw_channel#

Warning

This module is in an early, experimental state. Do not rely on its APIs.

API reference#

enum Property#

Basic properties of a Channel. A Channel type can convert to any other Channel for which it supports the required properties. For example, a kReadable and kWritable channel may be passed to an API that only requires kReadable.

Values:

enumerator kReliable#
enumerator kReadable#
enumerator kWritable#
enumerator kSeekable#
enum class DataType : uint8_t#

The type of data exchanged in Channel read and write calls. Unlike Property, Channels with different DataTypes cannot be used interchangeably.

Values:

enumerator kByte#
enumerator kDatagram#
enum Whence#

Positions from which to seek.

Values:

enumerator kBeginning#

Seek from the beginning of the channel. The offset is a direct offset into the data.

enumerator kCurrent#

Seek from the current position in the channel. The offset is added to the current position. Use a negative offset to seek backwards.

Implementations may only support seeking within a limited range from the current position.

enumerator kEnd#

Seek from the end of the channel. The offset is added to the end position. Use a negative offset to seek backwards from the end.

using ByteReader = ByteChannel<kReliable, kReadable>#

Alias for a reliable ByteChannel that supports reading.

using ByteWriter = ByteChannel<kReliable, kWritable>#

Alias for a reliable ByteChannel that supports writing.

using ByteReaderWriter = ByteChannel<kReliable, kReadable, kWritable>#

Alias for a reliable ByteChannel that supports reading and writing.

using ReliableDatagramReader = DatagramChannel<kReliable, kReadable>#

Alias for a reliable DatagramChannel that supports reading.

using ReliableDatagramWriter = DatagramChannel<kReliable, kWritable>#

Alias for a reliable DatagramChannel that supports writing.

using ReliableDatagramReaderWriter = DatagramChannel<kReliable, kReadable, kWritable>#

Alias for a reliable DatagramChannel that supports reading and writing.

using DatagramReader = DatagramChannel<kReadable>#

Alias for an unreliable DatagramChannel that supports reading.

using DatagramWriter = DatagramChannel<kWritable>#

Alias for an unreliable DatagramChannel that supports writing.

using DatagramReaderWriter = DatagramChannel<kReadable, kWritable>#

Alias for an unreliable DatagramChannel that supports reading and writing.

class WriteToken#

Represents a write operation. WriteToken can be used to track whether a particular write has been flushed.

class Channel#

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 Poll methods are only required to remember the latest pw::async2::Context that was provided.

Subclassed by pw::channel::ByteChannel< kProperties >, pw::channel::DatagramChannel< kProperties >

Public Functions

inline async2::Poll<Result<multibuf::MultiBuf>> PollRead(async2::Context &cx)#

Read API.

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. For byte stream channels, each successful read yields some number of bytes.

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

  • 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.

inline async2::Poll<Result<multibuf::MultiBuf>> PollRead(async2::Context &cx, size_t max_bytes)#

On byte stream channels, reads up to max_bytes from the channel. This function is hidden on datagram-oriented channels.

inline async2::Poll PollReadyToWrite(pw::async2::Context &cx)#

Write API.

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.

If Ready is returned, a single caller may proceed to Write.

If Pending is returned, cx will be awoken when the channel becomes writeable again.

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

multibuf::MultiBufAllocator &GetWriteAllocator()#

Gives access to an allocator for write buffers. The MultiBufAllocator provides an asynchronous API for obtaining a buffer.

This allocator must only be used to allocate the next argument to Write. The allocator must be used at most once per call to Write, and the returned MultiBuf must not be combined with any other MultiBuf s or Chunk s.

Write allocation attempts will always return std::nullopt for channels that do not support writing.

inline Result<WriteToken> Write(multibuf::MultiBuf &&data)#

Writes using a previously allocated MultiBuf. Returns a token that refers to this write. These tokens are monotonically increasing, and FlushPoll() 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 GetWriteAllocator() 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 GetWriteAllocator.

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

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.

inline async2::Poll<Result<WriteToken>> PollFlush(async2::Context &cx)#

Flushes pending writes.

Returns a async2::Poll indicating whether or not flushing has completed.

  • Ready(OK) - All data has been successfully flushed.

  • Ready(UNIMPLEMENTED) - The channel does not support writing.

  • Ready(FAILED_PRECONDITION) - The channel is closed.

  • Pending - Data remains to be flushed.

async2::Poll<Status> 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 PollRead 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.

  • 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.

size_t Position() const#

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

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

inline async2::Poll<pw::Status> PollClose(async2::Context &cx)#

Closes the channel, flushing any data.

  • 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.

template<Property... kProperties>
class ByteChannel : public pw::channel::Channel#

A ByteChannel exchanges data as a stream of bytes.

template<Property... kProperties>
class DatagramChannel : public pw::channel::Channel#

A DatagramChannel exchanges data as a series of datagrams.