Poll

Overview

Statuses for asynchronous operations.

Classes
struct	pw::async2::ReadyType
struct	pw::async2::PendingType
class	pw::async2::Poll< T >
class	pw::async2::Poll< void >
struct	pw::async2::UnwrapPoll< T >
struct	pw::async2::UnwrapPoll< Poll< T > >

Macros
#define	PW_AWAIT(...)   PW_DELEGATE_BY_ARG_COUNT(_PW_AWAIT_, __VA_ARGS__)
	Poll and resolve a future or return Pending if not ready.
#define	PW_ASYNC2_POLL_NODISCARD
#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)

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

Functions
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.
template<>
StatusWithSize	pw::ToString (const async2::ReadyType &, span< char > buffer)
template<>
StatusWithSize	pw::ToString (const async2::PendingType &, span< char > buffer)
template<typename T >
StatusWithSize	pw::ToString (const async2::Poll< T > &poll, span< char > buffer)
template<>
StatusWithSize	pw::ToString (const async2::Poll<> &poll, span< char > buffer)

Macro Definition Documentation

PW_ASYNC2_POLL_NODISCARD

#define PW_ASYNC2_POLL_NODISCARD

Value:

  PW_NODISCARD_STR(                                                      \
      "`Poll`-returning functions may or may not have completed. Their " \
      "return value should be examined.")

PW_AWAIT

#define PW_AWAIT

(

...

)

PW_DELEGATE_BY_ARG_COUNT(_PW_AWAIT_, __VA_ARGS__)

Poll and resolve a future or return Pending if not ready.

PW_AWAIT polls the provided future, returning Pending from the current function if the future is not yet ready. When the future completes, PW_AWAIT evaluates to the result of the future. This macro is convenient for writing DoPend implementations that need to wait on other futures.

Warning

PW_AWAIT does not extend the lifetime of the future. The future must remain valid until it completes. Do not use PW_AWAIT with temporary futures unless you are certain they will complete immediately.

Parameters:

• variable_declaration - (Optional) The variable declaration to which the future's result will be assigned. For example: auto result or int value.
• future - The pw::async2::Future to poll.
• context - The pw::async2::Context& with which to poll the future.

Usage:

PW_AWAIT(future, context): Waits for future to complete. Use this for futures that return void.

PW_AWAIT(variable_declaration, future, context): Waits for future to complete and assigns the result to variable_declaration.

Examples:

// Wait for a void future to complete:
PW_AWAIT(async_work_future_, cx);
 
// Wait for a value and assign it:
PW_AWAIT(auto result, async_value_future_, cx);
 
// Wait for a value and assign it to an existing variable:
int value;
PW_AWAIT(value, async_int_future_, cx);
 
// If the future needs to be created or has completed, restart it:
if (!my_future_.is_pendable()) {
  my_future_ = StartAsyncWork();
}
PW_AWAIT(auto result, my_future_, cx);

Expansion:

PW_AWAIT expands to code that pends the future, checks for readiness, and returns Pending or unwraps the value.

For example, PW_AWAIT(auto value, future, cx) expands roughly to:

auto&& _pw_poll_result = future.Pend(cx);
if (_pw_poll_result.IsPending()) {
  return Pending();
}
auto value = std::move(*_pw_poll_result);

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

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 >

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.

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