Overview

Core primitives such as tasks, dispatchers, polls, contexts, and wakers.

Classes
class	pw::async2::Context

class	pw::async2::Dispatcher
	A single-threaded cooperatively scheduled runtime for async tasks. More...

struct	pw::async2::ReadyType

struct	pw::async2::PendingType

class	pw::async2::Poll< T >

struct	pw::async2::UnwrapPoll< T >

struct	pw::async2::UnwrapPoll< Poll< T > >

class	pw::async2::Task

class	pw::async2::Waker

Macros
#define	PW_ASYNC2_CONFIG_LOG_LEVEL PW_LOG_LEVEL_INFO
	The log level to use for this module. Logs below this level are omitted.

#define	PW_ASYNC2_CONFIG_LOG_MODULE_NAME "PW_ASYNC2"
	The log module name to use for this module.

#define	PW_ASYNC2_DEBUG_WAIT_REASON 1

#define	PW_ASYNC_TASK_NAME(name) PW_LOG_TOKEN_EXPR("pw_async2", name)
	Generates a token for use as a task name.

#define	PW_TRY_READY(expr)
	Returns `Poll::Pending()` if `expr` is `Poll::Pending()`.

#define	PW_TRY_READY_ASSIGN(lhs, expression) _PW_TRY_READY_ASSIGN(_PW_TRY_READY_UNIQUE(__LINE__), lhs, expression)

#define	PW_ASYNC_STORE_WAKER(context, waker_or_queue_out, wait_reason_string)

#define	PW_ASYNC_TRY_STORE_WAKER( context, waker_or_queue_out, wait_reason_string)

#define	PW_ASYNC_CLONE_WAKER(waker_in, waker_or_queue_out, wait_reason_string)

#define	PW_ASYNC_TRY_CLONE_WAKER( waker_in, waker_or_queue_out, wait_reason_string)

Typedefs
using	pw::async2::Poll< T >::value_type = T

template<typename T >
using	pw::async2::PollResult = Poll< Result< T > >
	Convenience alias for `pw::async2::Poll<pw::Result<T>>`.

template<typename T >
using	pw::async2::PollOptional = Poll< std::optional< T > >
	Convenience alias for Poll<std::optional>.

using	pw::async2::UnwrapPoll< T >::Type = T

using	pw::async2::UnwrapPoll< Poll< T > >::Type = T

Functions
	pw::async2::Poll< T >::Poll ()=delete
	Basic constructors.

constexpr	pw::async2::Poll< T >::Poll (const Poll &)=default

constexpr Poll &	pw::async2::Poll< T >::operator= (const Poll &)=default

constexpr	pw::async2::Poll< T >::Poll (Poll &&)=default

constexpr Poll &	pw::async2::Poll< T >::operator= (Poll &&)=default

template<typename U , internal_poll::EnableIfImplicitlyConvertible< value_type, const U & > = 0>
constexpr	pw::async2::Poll< T >::Poll (const Poll< U > &other)

template<typename U , internal_poll::EnableIfImplicitlyConvertible< value_type, U && > = 0>
constexpr	pw::async2::Poll< T >::Poll (Poll< U > &&other)

template<typename U = value_type, internal_poll::EnableIfImplicitlyInitializable< value_type, U > = 0>
constexpr	pw::async2::Poll< T >::Poll (U &&u)

template<typename... Args>
constexpr	pw::async2::Poll< T >::Poll (std::in_place_t, Args &&... args)

constexpr	pw::async2::Poll< T >::Poll (value_type &&value)

constexpr Poll &	pw::async2::Poll< T >::operator= (value_type &&value)

constexpr	pw::async2::Poll< T >::Poll (PendingType) noexcept

constexpr Poll &	pw::async2::Poll< T >::operator= (PendingType) noexcept

constexpr bool	pw::async2::Poll< T >::IsReady () const noexcept
	Returns whether or not this value is `Ready`.

constexpr bool	pw::async2::Poll< T >::IsPending () const noexcept
	Returns whether or not this value is `Pending`.

constexpr Poll	pw::async2::Poll< T >::Readiness () const noexcept

constexpr value_type &	pw::async2::Poll< T >::value () &noexcept

constexpr const value_type &	pw::async2::Poll< T >::value () const &noexcept

constexpr value_type &&	pw::async2::Poll< T >::value () &&noexcept

constexpr const value_type &&	pw::async2::Poll< T >::value () const &&noexcept

constexpr const value_type *	pw::async2::Poll< T >::operator-> () const noexcept

constexpr value_type *	pw::async2::Poll< T >::operator-> () noexcept

constexpr const value_type &	pw::async2::Poll< T >::operator* () const &noexcept

constexpr value_type &	pw::async2::Poll< T >::operator* () &noexcept

constexpr const value_type &&	pw::async2::Poll< T >::operator* () const &&noexcept

constexpr value_type &&	pw::async2::Poll< T >::operator* () &&noexcept

constexpr void	pw::async2::Poll< T >::IgnorePoll () const

template<typename T >
	pw::async2::Poll (T value) -> Poll< T >

template<typename T >
constexpr bool	pw::async2::operator== (const Poll< T > &lhs, const Poll< T > &rhs)

template<typename T >
constexpr bool	pw::async2::operator!= (const Poll< T > &lhs, const Poll< T > &rhs)

template<typename T >
constexpr bool	pw::async2::operator== (const Poll< T > &lhs, PendingType)
	Returns whether `lhs` is pending.

template<typename T >
constexpr bool	pw::async2::operator!= (const Poll< T > &lhs, PendingType)
	Returns whether `lhs` is not pending.

template<typename T >
constexpr bool	pw::async2::operator== (PendingType, const Poll< T > &rhs)
	Returns whether `rhs` is pending.

template<typename T >
constexpr bool	pw::async2::operator!= (PendingType, const Poll< T > &rhs)
	Returns whether `rhs` is not pending.

constexpr bool	pw::async2::operator== (ReadyType, ReadyType)

constexpr bool	pw::async2::operator!= (ReadyType, ReadyType)

constexpr bool	pw::async2::operator== (PendingType, PendingType)

constexpr bool	pw::async2::operator!= (PendingType, PendingType)

constexpr Poll	pw::async2::Ready ()
	Returns a value indicating completion.

template<typename T , typename... Args>
constexpr Poll< T >	pw::async2::Ready (std::in_place_t, Args &&... args)

template<typename T >
constexpr Poll< std::remove_reference_t< T > >	pw::async2::Ready (T &&value)
	Returns a value indicating completion with some result.

constexpr PendingType	pw::async2::Pending ()
	Returns a value indicating that an operation was not yet able to complete.

Macro Definition Documentation

◆ PW_ASYNC2_DEBUG_WAIT_REASON

#define PW_ASYNC2_DEBUG_WAIT_REASON 1

Controls how the wait_reason_string argument to

embed:rst:inline :c:macro:`PW_ASYNC_STORE_WAKER`

and

embed:rst:inline :c:macro:`PW_ASYNC_CLONE_WAKER`

is used. If enabled, wait reasons are stored within their wakers, allowing easier debugging of sleeping tasks.

Enabled by default.

Note: The module dependencies of pw_async2 vary based on on the value of PW_ASYNC2_DEBUG_WAIT_REASON. When building pw_async2 with Bazel, you should NOT set this module config by adding one of the following constraint_values to the target platform:

@pigweed//pw_async2:debug_wait_reason_disabled (default)
@pigweed//pw_async2:debug_wait_reason_enabled

◆ PW_ASYNC_CLONE_WAKER

#define PW_ASYNC_CLONE_WAKER	(	waker_in,
		waker_or_queue_out,
		wait_reason_string
	)

Value:

  do {                                                                         \
    bool waker_or_queue_had_space = PW_ASYNC_TRY_CLONE_WAKER(                  \
        waker_in, waker_or_queue_out, wait_reason_string);                     \
    PW_ASSERT(waker_or_queue_had_space);                                       \
  } while (0)

Attempts to store a waker associated with waker_in into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, crashes.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.

◆ PW_ASYNC_STORE_WAKER

#define PW_ASYNC_STORE_WAKER	(	context,
		waker_or_queue_out,
		wait_reason_string
	)

Value:

  do {                                                                        \
    bool waker_or_queue_had_space = PW_ASYNC_TRY_STORE_WAKER(                 \
        context, waker_or_queue_out, wait_reason_string);                     \
    PW_ASSERT(waker_or_queue_had_space);                                      \
  } while (0)

Attempts to store a waker associated with the current context into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, crashes.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.

◆ PW_ASYNC_TRY_CLONE_WAKER

#define PW_ASYNC_TRY_CLONE_WAKER	(	waker_in,
		waker_or_queue_out,
		wait_reason_string
	)

Value:

  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::CloneWaker, \
                          waker_in,                           \
                          waker_or_queue_out,                 \
                          wait_reason_string)

Attempts to store a waker associated with waker_in into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, returns false and does not modify it.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.

◆ PW_ASYNC_TRY_STORE_WAKER

#define PW_ASYNC_TRY_STORE_WAKER	(	context,
		waker_or_queue_out,
		wait_reason_string
	)

Value:

  _PW_ASYNC_TRY_GET_WAKER(::pw::async2::internal::StoreWaker, \
                          context,                            \
                          waker_or_queue_out,                 \
                          wait_reason_string)

Attempts to store a waker associated with the current context into waker_or_queue_out. If the waker cannot be stored into waker_or_queue_out due to the target waker already referencing a task or the queue being full, returns false and does not modify it.

When the stored waker is later awoken with :cpp:func:pw::async2::Waker::Wake, the :cpp:class:pw::async2::Task associated with cx will be awoken and its DoPend method will be invoked again.

wait_reason_string is a human-readable description of why the task is blocked. If the module configuration option PW_ASYNC2_DEBUG_WAIT_REASON is set, this string will be stored with the waker and reported by Dispatcher::LogRegisteredTasks when its associated task is blocked.

◆ PW_TRY_READY

#define PW_TRY_READY ( expr )

Value:

  do {                                \
    if ((expr).IsPending()) {         \
      return ::pw::async2::Pending(); \
    }                                 \
  } while (0)

Returns Poll::Pending() if expr is Poll::Pending().

◆ PW_TRY_READY_ASSIGN

#define PW_TRY_READY_ASSIGN	(	lhs,
		expression
	)	_PW_TRY_READY_ASSIGN(_PW_TRY_READY_UNIQUE(__LINE__), lhs, expression)

Returns Poll::Pending() if expr is Poll::Pending(). If expression is Poll::Ready(), assigns the inner value to lhs.

Function Documentation

◆ IgnorePoll()

template<typename T = ReadyType>

constexpr void pw::async2::Poll< T >::IgnorePoll ( ) const

inlineconstexpr

Ignores the Poll value.

This method does nothing except prevent no_discard or unused variable warnings from firing.

◆ operator!=()

template<typename T >

constexpr bool pw::async2::operator!=	(	const Poll< T > &	lhs,
		const Poll< T > &	rhs
	)

constexpr

Returns whether two instances of Poll<T> are unequal.

Note that this comparison operator will return false if both values are currently Pending, even if the eventual results of each operation might differ.

◆ operator*()

template<typename T = ReadyType>

constexpr const value_type & pw::async2::Poll< T >::operator* ( ) const &

inlineconstexprnoexcept

Returns the inner value.

This must only be called if IsReady() returned true.

◆ operator->()

template<typename T = ReadyType>

constexpr const value_type * pw::async2::Poll< T >::operator-> ( ) const

inlineconstexprnoexcept

Accesses the inner value.

This must only be called if IsReady() returned true.

◆ operator==()

template<typename T >

constexpr bool pw::async2::operator==	(	const Poll< T > &	lhs,
		const Poll< T > &	rhs
	)

constexpr

Returns whether two instances of Poll<T> are equal.

Note that this comparison operator will return true if both values are currently Pending, even if the eventual results of each operation might differ.

◆ Poll()

template<typename T = ReadyType>

template<typename U , internal_poll::EnableIfImplicitlyConvertible< value_type, const U & > = 0>

constexpr pw::async2::Poll< T >::Poll ( const Poll< U > & other )

inlineconstexpr

Constructs a new Poll<T> from a Poll<U> where T is constructible from U.

To avoid ambiguity, this constructor is disabled if T is also constructible from Poll<U>.

This constructor is explicit if and only if the corresponding construction of T from U is explicit.

◆ Readiness()

template<typename T = ReadyType>

constexpr Poll pw::async2::Poll< T >::Readiness ( ) const

inlineconstexprnoexcept

Returns a Poll<> without the inner value whose readiness matches that of this.

◆ Ready()

template<typename T , typename... Args>

constexpr Poll< T > pw::async2::Ready	(	std::in_place_t	,
		Args &&...	args
	)

constexpr

Returns a value indicating completion with some result (constructed in-place).

◆ value()

template<typename T = ReadyType>

constexpr value_type & pw::async2::Poll< T >::value ( ) &

inlineconstexprnoexcept

Returns the inner value.

This must only be called if IsReady() returned true.

Overview

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ PW_ASYNC2_DEBUG_WAIT_REASON

◆ PW_ASYNC_CLONE_WAKER

◆ PW_ASYNC_STORE_WAKER

◆ PW_ASYNC_TRY_CLONE_WAKER

◆ PW_ASYNC_TRY_STORE_WAKER

◆ PW_TRY_READY

◆ PW_TRY_READY_ASSIGN

Function Documentation

◆ IgnorePoll()

◆ operator!=()

◆ operator*()

◆ operator->()

◆ operator==()

◆ Poll()

◆ Readiness()

◆ Ready()

◆ value()