Channels

Overview

Send objects between tasks or threads. Learn more: Channels

Classes
class	pw::async2::Receiver< T >
	A receiver which reads values from an asynchronous channel. More...
class	pw::async2::ReceiveFuture< T >
class	pw::async2::Sender< T >
	A sender which writes values to an asynchronous channel. More...
class	pw::async2::SendFuture< T >
class	pw::async2::ReserveSendFuture< T >
class	pw::async2::SendReservation< T >
class	pw::async2::ChannelStorage< T, kCapacity >
class	pw::async2::internal::Channel< T >
class	pw::async2::internal::BaseChannel
class	pw::async2::internal::BaseChannelFuture
class	pw::async2::internal::ChannelFuture< Derived, T, FutureValue >
class	pw::async2::internal::DynamicChannel< T >
class	pw::async2::internal::ChannelHandle< T >
class	pw::async2::MpmcChannelHandle< T >
	A handle to a multi-producer, multi-consumer channel. More...
class	pw::async2::MpscChannelHandle< T >
	A handle to a multi-producer, single-consumer channel. More...
class	pw::async2::SpmcChannelHandle< T >
	A handle to a single-producer, multi-consumer channel. More...
class	pw::async2::SpscChannelHandle< T >
	A handle to a single-producer, single-consumer channel. More...

Typedefs
using	pw::async2::internal::ChannelFuture< Derived, T, FutureValue >::value_type = FutureValue

Enumerations
enum	AllowClosed { kAllowClosed }

Functions
void	pw::async2::internal::BaseChannel::lock ()
void	pw::async2::internal::BaseChannel::unlock ()
bool	pw::async2::internal::BaseChannel::is_open ()
bool	pw::async2::internal::BaseChannel::is_open_locked () const
bool	pw::async2::internal::BaseChannel::active_locked () const
void	pw::async2::internal::BaseChannel::RemoveRefAndDestroyIfUnreferenced ()
void	pw::async2::internal::BaseChannel::Close ()
void	pw::async2::internal::BaseChannel::add_send_future (BaseChannelFuture &future)
void	pw::async2::internal::BaseChannel::add_receive_future (BaseChannelFuture &future)
void	pw::async2::internal::BaseChannel::DropReservationAndRemoveRef ()
void	pw::async2::internal::BaseChannel::add_receiver ()
void	pw::async2::internal::BaseChannel::add_sender ()
void	pw::async2::internal::BaseChannel::add_handle ()
void	pw::async2::internal::BaseChannel::add_reservation ()
void	pw::async2::internal::BaseChannel::remove_reservation ()
void	pw::async2::internal::BaseChannel::remove_sender ()
void	pw::async2::internal::BaseChannel::remove_receiver ()
void	pw::async2::internal::BaseChannel::remove_handle ()
void	pw::async2::internal::BaseChannel::add_ref ()
void	pw::async2::internal::BaseChannel::WakeOneReceiver ()
void	pw::async2::internal::BaseChannel::WakeOneSender ()
uint16_t	pw::async2::internal::BaseChannel::reservations () const
	pw::async2::internal::BaseChannelFuture::BaseChannelFuture (const BaseChannelFuture &)=delete
BaseChannelFuture &	pw::async2::internal::BaseChannelFuture::operator= (const BaseChannelFuture &)=delete
BaseChannelFuture &	pw::async2::internal::BaseChannelFuture::operator= (BaseChannelFuture &&)=delete
bool	pw::async2::internal::BaseChannelFuture::is_complete () const
	True if the future has returned Ready().
void	pw::async2::internal::BaseChannelFuture::Wake ()
	pw::async2::internal::BaseChannelFuture::BaseChannelFuture (BaseChannel *channel)
	pw::async2::internal::BaseChannelFuture::BaseChannelFuture (BaseChannel *channel, AllowClosed)
	pw::async2::internal::BaseChannelFuture::BaseChannelFuture (BaseChannelFuture &&other)
BaseChannelFuture &	pw::async2::internal::BaseChannelFuture::MoveAssignFrom (BaseChannelFuture &other)
void	pw::async2::internal::BaseChannelFuture::RemoveFromChannel ()
bool	pw::async2::internal::BaseChannelFuture::StoreWakerForReceiveIfOpen (Context &cx)
void	pw::async2::internal::BaseChannelFuture::StoreWakerForSend (Context &cx)
void	pw::async2::internal::BaseChannelFuture::StoreWakerForReserveSend (Context &cx)
void	pw::async2::internal::BaseChannelFuture::MarkCompleted ()
void	pw::async2::internal::BaseChannelFuture::Complete ()
BaseChannel *	pw::async2::internal::BaseChannelFuture::base_channel () PW_LOCK_RETURNED(channel_)
Poll< value_type >	pw::async2::internal::ChannelFuture< Derived, T, FutureValue >::Pend (Context &cx)
	pw::async2::internal::ChannelFuture< Derived, T, FutureValue >::ChannelFuture (Channel< T > *channel)
	pw::async2::internal::ChannelFuture< Derived, T, FutureValue >::ChannelFuture (Channel< T > *channel, AllowClosed)
	pw::async2::internal::ChannelFuture< Derived, T, FutureValue >::ChannelFuture (ChannelFuture &&other)
Channel< T > *	pw::async2::internal::ChannelFuture< Derived, T, FutureValue >::channel () PW_LOCK_RETURNED(this -> base_channel())
Sender< T >	pw::async2::internal::Channel< T >::CreateSender ()
Receiver< T >	pw::async2::internal::Channel< T >::CreateReceiver ()
void	pw::async2::internal::Channel< T >::PushAndWake (T &&value)
void	pw::async2::internal::Channel< T >::PushAndWake (const T &value)
template<typename... Args>
void	pw::async2::internal::Channel< T >::EmplaceAndWake (Args &&... args)
T	pw::async2::internal::Channel< T >::PopAndWake ()
bool	pw::async2::internal::Channel< T >::full () const
uint16_t	pw::async2::internal::Channel< T >::remaining_capacity ()
uint16_t	pw::async2::internal::Channel< T >::remaining_capacity_locked () const
uint16_t	pw::async2::internal::Channel< T >::capacity () const
bool	pw::async2::internal::Channel< T >::empty ()
template<typename U >
Status	pw::async2::internal::Channel< T >::TrySend (U &&value)
Result< T >	pw::async2::internal::Channel< T >::TryReceive ()
Result< SendReservation< T > >	pw::async2::internal::Channel< T >::TryReserveSend ()
template<typename... Args>
void	pw::async2::internal::Channel< T >::CommitReservationAndRemoveRef (Args &&... args)
constexpr	pw::async2::internal::Channel< T >::Channel (FixedDeque< T > &&deque)
template<size_t kAlignment, size_t kCapacity>
	pw::async2::internal::Channel< T >::Channel (containers::Storage< kAlignment, kCapacity > &storage)
Deallocator *	pw::async2::internal::Channel< T >::deallocator () const
static Channel< T > *	pw::async2::internal::DynamicChannel< T >::Allocate (Allocator &alloc, uint16_t capacity)
	pw::async2::internal::DynamicChannel< T >::DynamicChannel (FixedDeque< T > &&deque)
	pw::async2::internal::ChannelHandle< T >::ChannelHandle (const ChannelHandle &other)
ChannelHandle &	pw::async2::internal::ChannelHandle< T >::operator= (const ChannelHandle &other)
	pw::async2::internal::ChannelHandle< T >::ChannelHandle (ChannelHandle &&other) noexcept
ChannelHandle &	pw::async2::internal::ChannelHandle< T >::operator= (ChannelHandle &&other) noexcept
bool	pw::async2::internal::ChannelHandle< T >::is_open () const
Sender< T >	pw::async2::internal::ChannelHandle< T >::CreateSender ()
Receiver< T >	pw::async2::internal::ChannelHandle< T >::CreateReceiver ()
void	pw::async2::internal::ChannelHandle< T >::Close ()
void	pw::async2::internal::ChannelHandle< T >::Release ()
	pw::async2::internal::ChannelHandle< T >::ChannelHandle (internal::Channel< T > &channel)
bool	pw::async2::ChannelStorage< T, kCapacity >::active () const
constexpr uint16_t	pw::async2::ChannelStorage< T, kCapacity >::capacity () const
	pw::async2::ReceiveFuture< T >::ReceiveFuture (ReceiveFuture &&other)
ReceiveFuture &	pw::async2::ReceiveFuture< T >::operator= (ReceiveFuture &&other)
	pw::async2::Receiver< T >::Receiver (const Receiver &other)=delete
Receiver &	pw::async2::Receiver< T >::operator= (const Receiver &other)=delete
	pw::async2::Receiver< T >::Receiver (Receiver &&other) noexcept
Receiver &	pw::async2::Receiver< T >::operator= (Receiver &&other) noexcept
Result< T >	pw::async2::Receiver< T >::BlockingReceive (Dispatcher &dispatcher, chrono::SystemClock::duration timeout=internal::Channel< T >::kWaitForever)
ReceiveFuture< T >	pw::async2::Receiver< T >::Receive ()
Result< T >	pw::async2::Receiver< T >::TryReceive ()
void	pw::async2::Receiver< T >::Disconnect ()
bool	pw::async2::Receiver< T >::is_open () const
	Returns true if the channel is open.
	pw::async2::SendFuture< T >::SendFuture (SendFuture &&other)
SendFuture &	pw::async2::SendFuture< T >::operator= (SendFuture &&other)
	pw::async2::SendReservation< T >::SendReservation (const SendReservation &other)=delete
SendReservation &	pw::async2::SendReservation< T >::operator= (const SendReservation &other)=delete
	pw::async2::SendReservation< T >::SendReservation (SendReservation &&other)
SendReservation &	pw::async2::SendReservation< T >::operator= (SendReservation &&other)
template<typename... Args>
void	pw::async2::SendReservation< T >::Commit (Args &&... args)
	Commits a value to a reserved slot.
void	pw::async2::SendReservation< T >::Cancel ()
	Releases the reservation, making the space available for other senders.
	pw::async2::ReserveSendFuture< T >::ReserveSendFuture (ReserveSendFuture &&other)
ReserveSendFuture &	pw::async2::ReserveSendFuture< T >::operator= (ReserveSendFuture &&other)
	pw::async2::Sender< T >::Sender (const Sender &other)=delete
Sender &	pw::async2::Sender< T >::operator= (const Sender &other)=delete
	pw::async2::Sender< T >::Sender (Sender &&other) noexcept
Sender &	pw::async2::Sender< T >::operator= (Sender &&other) noexcept
template<typename U >
SendFuture< T >	pw::async2::Sender< T >::Send (U &&value)
ReserveSendFuture< T >	pw::async2::Sender< T >::ReserveSend ()
Result< SendReservation< T > >	pw::async2::Sender< T >::TryReserveSend ()
Status	pw::async2::Sender< T >::TrySend (const T &value)
Status	pw::async2::Sender< T >::TrySend (T &&value)
Status	pw::async2::Sender< T >::BlockingSend (Dispatcher &dispatcher, const T &value, chrono::SystemClock::duration timeout=internal::Channel< T >::kWaitForever)
Status	pw::async2::Sender< T >::BlockingSend (Dispatcher &dispatcher, T &&value, chrono::SystemClock::duration timeout=internal::Channel< T >::kWaitForever)
void	pw::async2::Sender< T >::Disconnect ()
uint16_t	pw::async2::Sender< T >::remaining_capacity () const
	Returns the remaining capacity of the channel.
uint16_t	pw::async2::Sender< T >::capacity () const
	Returns the maximum capacity of the channel.
bool	pw::async2::Sender< T >::is_open () const
	Returns true if the channel is open.
template<typename T >
std::optional< MpmcChannelHandle< T > >	pw::async2::CreateMpmcChannel (Allocator &alloc, uint16_t capacity)
template<typename T , uint16_t kCapacity>
MpmcChannelHandle< T >	pw::async2::CreateMpmcChannel (ChannelStorage< T, kCapacity > &storage)
template<typename T >
std::optional< std::tuple< MpscChannelHandle< T >, Receiver< T > > >	pw::async2::CreateMpscChannel (Allocator &alloc, uint16_t capacity)
template<typename T , uint16_t kCapacity>
std::tuple< MpscChannelHandle< T >, Receiver< T > >	pw::async2::CreateMpscChannel (ChannelStorage< T, kCapacity > &storage)
template<typename T >
std::optional< std::tuple< SpmcChannelHandle< T >, Sender< T > > >	pw::async2::CreateSpmcChannel (Allocator &alloc, uint16_t capacity)
template<typename T , uint16_t kCapacity>
std::tuple< SpmcChannelHandle< T >, Sender< T > >	pw::async2::CreateSpmcChannel (ChannelStorage< T, kCapacity > &storage)
template<typename T >
std::optional< std::tuple< SpscChannelHandle< T >, Sender< T >, Receiver< T > > >	pw::async2::CreateSpscChannel (Allocator &alloc, uint16_t capacity)
template<typename T , uint16_t kCapacity>
std::tuple< SpscChannelHandle< T >, Sender< T >, Receiver< T > >	pw::async2::CreateSpscChannel (ChannelStorage< T, kCapacity > &storage)

Variables
static constexpr chrono::SystemClock::duration	pw::async2::internal::BaseChannel::kWaitForever

Friends
template<typename U >
class	pw::async2::Receiver< T >::internal::Channel
class	pw::async2::SendReservation< T >::ReserveSendFuture< T >
class	pw::async2::SendReservation< T >::Sender< T >
template<typename U >
class	pw::async2::Sender< T >::internal::Channel
template<typename U >
std::optional< MpmcChannelHandle< U > >	pw::async2::MpmcChannelHandle< T >::CreateMpmcChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
MpmcChannelHandle< U >	pw::async2::MpmcChannelHandle< T >::CreateMpmcChannel (ChannelStorage< U, kCapacity > &storage)
template<typename U >
std::optional< std::tuple< MpscChannelHandle< U >, Receiver< U > > >	pw::async2::MpscChannelHandle< T >::CreateMpscChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
std::tuple< MpscChannelHandle< U >, Receiver< U > >	pw::async2::MpscChannelHandle< T >::CreateMpscChannel (ChannelStorage< U, kCapacity > &storage)
template<typename U >
std::optional< std::tuple< SpmcChannelHandle< U >, Sender< U > > >	pw::async2::SpmcChannelHandle< T >::CreateSpmcChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
std::tuple< SpmcChannelHandle< U >, Sender< U > >	pw::async2::SpmcChannelHandle< T >::CreateSpmcChannel (ChannelStorage< U, kCapacity > &storage)
template<typename U >
std::optional< std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > > >	pw::async2::SpscChannelHandle< T >::CreateSpscChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > >	pw::async2::SpscChannelHandle< T >::CreateSpscChannel (ChannelStorage< U, kCapacity > &storage)
template<typename U , uint16_t kCap>
std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > >	pw::async2::ChannelStorage< T, kCapacity >::CreateSpscChannel (ChannelStorage< U, kCap > &storage)
template<typename U , uint16_t kCap>
std::tuple< MpscChannelHandle< U >, Receiver< U > >	pw::async2::ChannelStorage< T, kCapacity >::CreateMpscChannel (ChannelStorage< U, kCap > &storage)
template<typename U , uint16_t kCap>
std::tuple< SpmcChannelHandle< U >, Sender< U > >	pw::async2::ChannelStorage< T, kCapacity >::CreateSpmcChannel (ChannelStorage< U, kCap > &storage)
template<typename U , uint16_t kCap>
MpmcChannelHandle< U >	pw::async2::ChannelStorage< T, kCapacity >::CreateMpmcChannel (ChannelStorage< U, kCap > &storage)
template<typename U >
std::optional< std::tuple< MpscChannelHandle< U >, Receiver< U > > >	pw::async2::Receiver< T >::CreateMpscChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
std::tuple< MpscChannelHandle< U >, Receiver< U > >	pw::async2::Receiver< T >::CreateMpscChannel (ChannelStorage< U, kCapacity > &storage)
template<typename U >
std::optional< std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > > >	pw::async2::Receiver< T >::CreateSpscChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > >	pw::async2::Receiver< T >::CreateSpscChannel (ChannelStorage< U, kCapacity > &storage)
template<typename U >
std::optional< std::tuple< SpmcChannelHandle< U >, Sender< U > > >	pw::async2::Sender< T >::CreateSpmcChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
std::tuple< SpmcChannelHandle< U >, Sender< U > >	pw::async2::Sender< T >::CreateSpmcChannel (ChannelStorage< U, kCapacity > &storage)
template<typename U >
std::optional< std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > > >	pw::async2::Sender< T >::CreateSpscChannel (Allocator &, uint16_t)
template<typename U , uint16_t kCapacity>
std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > >	pw::async2::Sender< T >::CreateSpscChannel (ChannelStorage< U, kCapacity > &storage)

Function Documentation

active()

template<typename T , uint16_t kCapacity>

bool pw::async2::ChannelStorage< T, kCapacity >::active ( ) const

inline

Returns true if this channel storage is in use. If false, the storage can either be reused or safely destroyed.

BlockingReceive()

template<typename T >

Result< T > pw::async2::Receiver< T >::BlockingReceive ( Dispatcher &  dispatcher, chrono::SystemClock::duration  timeout = internal::Channel<T>::kWaitForever  )

inline

Reads a value from the channel, blocking until it is available.

Returns

• OK: A value was successfully read from the channel.
• FAILED_PRECONDITION: The channel is closed.
• DEADLINE_EXCEEDED: The operation timed out.

This operation blocks the running thread until it is complete. It must not be called from an async context, or it will likely deadlock.

BlockingSend() [1/2]

template<typename T >

Status pw::async2::Sender< T >::BlockingSend ( Dispatcher &  dispatcher, const T &  value, chrono::SystemClock::duration  timeout = internal::Channel<T>::kWaitForever  )

inline

Synchronously attempts to send value to the channel, blocking until space is available or the channel is closed.

This operation blocks the running thread until it is complete. It must not be called from an async context, or it will likely deadlock.

Returns

• OK: The value was successfully sent to the channel.
• FAILED_PRECONDITION: The channel is closed.
• DEADLINE_EXCEEDED: The operation timed out.

BlockingSend() [2/2]

template<typename T >

Status pw::async2::Sender< T >::BlockingSend ( Dispatcher &  dispatcher, T &&  value, chrono::SystemClock::duration  timeout = internal::Channel<T>::kWaitForever  )

inline

Synchronously attempts to send value to the channel, blocking until space is available or the channel is closed.

This operation blocks the running thread until it is complete. It must not be called from an async context, or it will likely deadlock.

Returns

• OK: The value was successfully sent to the channel.
• FAILED_PRECONDITION: The channel is closed.
• DEADLINE_EXCEEDED: The operation timed out.

Close()

template<typename T >

void pw::async2::internal::ChannelHandle< T >::Close ( )

inline

Forces the channel to close, even if there are still active senders or receivers.

CreateMpmcChannel() [1/2]

template<typename T >

std::optional< MpmcChannelHandle< T > > pw::async2::CreateMpmcChannel	(	Allocator &	alloc,
		uint16_t	capacity
	)

Creates a dynamically allocated multi-producer, multi-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create senders and receivers. After all desired senders and receivers are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateMpmcChannel() [2/2]

template<typename T , uint16_t kCapacity>

MpmcChannelHandle< T > pw::async2::CreateMpmcChannel

(

ChannelStorage< T, kCapacity > &

storage

)

Creates a multi-producer, multi-consumer channel with provided static storage.

Returns a handle to the channel which may be used to create senders and receivers. After all desired senders and receivers are created, the handle can be dropped without affecting the channel.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

The provided storage must outlive the channel.

CreateMpscChannel() [1/2]

template<typename T >

std::optional< std::tuple< MpscChannelHandle< T >, Receiver< T > > > pw::async2::CreateMpscChannel	(	Allocator &	alloc,
		uint16_t	capacity
	)

Creates a dynamically allocated multi-producer, single-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create senders. After all desired senders are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateMpscChannel() [2/2]

template<typename T , uint16_t kCapacity>

std::tuple< MpscChannelHandle< T >, Receiver< T > > pw::async2::CreateMpscChannel

(

ChannelStorage< T, kCapacity > &

storage

)

Creates a multi-producer, single-consumer channel with provided static storage.

Returns a handle to the channel which may be used to create senders. After all desired senders are created, the handle can be dropped without affecting the channel.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

The provided storage must outlive the channel.

CreateReceiver()

template<typename T >

Receiver< T > pw::async2::internal::ChannelHandle< T >::CreateReceiver ( )

inline

Creates a new receiver for the channel, increasing the active receiver count. Cannot be called following Release.

CreateSender()

template<typename T >

Sender< T > pw::async2::internal::ChannelHandle< T >::CreateSender ( )

inline

Creates a new sender for the channel, increasing the active sender count. Cannot be called following Release.

CreateSpmcChannel() [1/2]

template<typename T >

std::optional< std::tuple< SpmcChannelHandle< T >, Sender< T > > > pw::async2::CreateSpmcChannel	(	Allocator &	alloc,
		uint16_t	capacity
	)

Creates a dynamically allocated single-producer, multi-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create receivers. After all desired receivers are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateSpmcChannel() [2/2]

template<typename T , uint16_t kCapacity>

std::tuple< SpmcChannelHandle< T >, Sender< T > > pw::async2::CreateSpmcChannel

(

ChannelStorage< T, kCapacity > &

storage

)

Creates a single-producer, multi-consumer channel with provided static storage.

Returns a handle to the channel which may be used to create receivers. After all desired receivers are created, the handle can be dropped without affecting the channel.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

The provided storage must outlive the channel.

CreateSpscChannel() [1/2]

template<typename T >

std::optional< std::tuple< SpscChannelHandle< T >, Sender< T >, Receiver< T > > > pw::async2::CreateSpscChannel	(	Allocator &	alloc,
		uint16_t	capacity
	)

Creates a dynamically allocated single-producer, single-consumer channel with a fixed storage capacity.

Returns a handle to the channel alongside the sender and receiver. The handle can be used to forcefully close the channel. If that is not required, it can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateSpscChannel() [2/2]

template<typename T , uint16_t kCapacity>

std::tuple< SpscChannelHandle< T >, Sender< T >, Receiver< T > > pw::async2::CreateSpscChannel

(

ChannelStorage< T, kCapacity > &

storage

)

Creates a single-producer, single-consumer channel with provided static storage.

Returns a handle to the channel alongside the sender and receiver. The handle can be used to forcefully close the channel. If that is not required, it can be dropped without affecting the channel.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

The provided storage must outlive the channel.

Destroy()

template<typename T >

void pw::async2::internal::DynamicChannel< T >::Destroy ( )

inlinefinalprivatevirtual

Reimplemented from pw::async2::internal::BaseChannel.

Disconnect() [1/2]

template<typename T >

void pw::async2::Receiver< T >::Disconnect ( )

inline

Removes this receiver from its channel, preventing the receiver from reading further values.

The channel may remain open if other receivers exist.

Disconnect() [2/2]

template<typename T >

void pw::async2::Sender< T >::Disconnect ( )

inline

Removes this sender from its channel, preventing it from writing further values.

The channel may remain open if other senders and receivers exist.

Receive()

template<typename T >

ReceiveFuture< T > pw::async2::Receiver< T >::Receive ( )

inline

Reads a value from the channel, blocking until it is available.

Returns a Future<std::optional<T>> which resolves to a T value if the read is successful, or std::nullopt if the channel is closed.

If there are multiple receivers for a channel, each of them compete for exclusive values.

Release()

template<typename T >

void pw::async2::internal::ChannelHandle< T >::Release ( )

inline

Drops the handle to the channel, preventing creation of new senders and receivers.

This function should always be called when the handle is no longer needed. Holding onto an unreleased handle can prevent the channel from being closed (and deallocated if the channel is dynamic).

ReserveSend()

template<typename T >

ReserveSendFuture< T > pw::async2::Sender< T >::ReserveSend ( )

inline

Returns a Future<std::optional<SendReservation>> which resolves to a SendReservation which can be used to write a value directly into the channel when space is available.

If the channel is closed, the future resolves to nullopt.

Send()

template<typename T >

template<typename U >

SendFuture< T > pw::async2::Sender< T >::Send ( U &&  value )

inline

Sends value through the channel, blocking until there is space.

Returns a Future<bool> which resolves to true if the value was successfully sent to the channel, or false if the channel is closed.

Note that a value being sent successfully does not guarantee that it will be read. If all corresponding receivers disconnect, any values still buffered in the channel are lost.

TryReceive()

template<typename T >

Result< T > pw::async2::Receiver< T >::TryReceive ( )

inline

Reads a value from the channel if one is available.

Returns

• OK: A value was successfully read from the channel.
• FAILED_PRECONDITION: The channel is closed.
• UNAVAILABLE: The channel is empty.

TryReserveSend()

template<typename T >

Result< SendReservation< T > > pw::async2::Sender< T >::TryReserveSend ( )

inline

Synchronously attempts to reserve a slot in the channel.

This operation is thread-safe and may be called from outside of an async context.

Returns

• OK: A SendReservation was successfully created.
• FAILED_PRECONDITION: The channel is closed.
• UNAVAILABLE: The channel is full.

TrySend() [1/2]

template<typename T >

Status pw::async2::Sender< T >::TrySend ( const T &  value )

inline

Synchronously attempts to send value if there is space in the channel.

This operation is thread-safe and may be called from outside of an async context.

Returns

• OK: The value was successfully sent to the channel.
• FAILED_PRECONDITION: The channel is closed.
• UNAVAILABLE: The channel is full.

TrySend() [2/2]

template<typename T >

Status pw::async2::Sender< T >::TrySend ( T &&  value )

inline

Synchronously attempts to send value if there is space in the channel.

This operation is thread-safe and may be called from outside of an async context.

Returns

• OK: The value was successfully sent to the channel.
• FAILED_PRECONDITION: The channel is closed.
• UNAVAILABLE: The channel is full.

Variable Documentation

kWaitForever

constexpr chrono::SystemClock::duration pw::async2::internal::BaseChannel::kWaitForever

staticconstexpr

Initial value:

=
      chrono::SystemClock::duration::max()

Friends

CreateMpmcChannel

template<typename T >

template<typename U >

std::optional< MpmcChannelHandle< U > > CreateMpmcChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated multi-producer, multi-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create senders and receivers. After all desired senders and receivers are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateMpscChannel [1/2]

template<typename T >

template<typename U >

std::optional< std::tuple< MpscChannelHandle< U >, Receiver< U > > > CreateMpscChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated multi-producer, single-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create senders. After all desired senders are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateMpscChannel [2/2]

template<typename T >

template<typename U >

std::optional< std::tuple< MpscChannelHandle< U >, Receiver< U > > > CreateMpscChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated multi-producer, single-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create senders. After all desired senders are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateSpmcChannel [1/2]

template<typename T >

template<typename U >

std::optional< std::tuple< SpmcChannelHandle< U >, Sender< U > > > CreateSpmcChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated single-producer, multi-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create receivers. After all desired receivers are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateSpmcChannel [2/2]

template<typename T >

template<typename U >

std::optional< std::tuple< SpmcChannelHandle< U >, Sender< U > > > CreateSpmcChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated single-producer, multi-consumer channel with a fixed storage capacity.

Returns a handle to the channel which may be used to create receivers. After all desired receivers are created, the handle can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateSpscChannel [1/3]

template<typename T >

template<typename U >

std::optional< std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > > > CreateSpscChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated single-producer, single-consumer channel with a fixed storage capacity.

Returns a handle to the channel alongside the sender and receiver. The handle can be used to forcefully close the channel. If that is not required, it can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateSpscChannel [2/3]

template<typename T >

template<typename U >

std::optional< std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > > > CreateSpscChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated single-producer, single-consumer channel with a fixed storage capacity.

Returns a handle to the channel alongside the sender and receiver. The handle can be used to forcefully close the channel. If that is not required, it can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.

CreateSpscChannel [3/3]

template<typename T >

template<typename U >

std::optional< std::tuple< SpscChannelHandle< U >, Sender< U >, Receiver< U > > > CreateSpscChannel ( Allocator &  alloc, uint16_t  capacity  )

friend

Creates a dynamically allocated single-producer, single-consumer channel with a fixed storage capacity.

Returns a handle to the channel alongside the sender and receiver. The handle can be used to forcefully close the channel. If that is not required, it can be dropped without affecting the channel.

All allocation occurs during the creation of the channel. After this function returns, usage of the channel is guaranteed not to allocate. If allocation fails, returns std::nullopt.

The channel remains open as long as at least either a handle, or at least one sender and one receiver exist.