pw::async2::FutureCore Class Reference

Overview

FutureCore provides common functionality for futures that need to be wakeable and stored in a list.

This class provides the core mechanism for:

• Storing a Waker to be woken up.
• Tracking future state.
• Being part of an IntrusiveList.

It is designed to be used as a member of a concrete future class (composition) rather than a base class, to simplify move semantics and object lifetime.

Inheritance diagram for pw::async2::FutureCore:

Public Member Functions
	FutureCore (FutureCore &&other) noexcept
FutureCore &	operator= (FutureCore &&other) noexcept
constexpr	FutureCore (FutureState::Pending)
constexpr	FutureCore (FutureState::ReadyForCompletion)
	FutureCore (const FutureCore &)=delete
FutureCore &	operator= (const FutureCore &)=delete
constexpr bool	is_pendable () const
constexpr bool	is_complete () const
constexpr bool	is_ready () const
constexpr bool	is_initialized () const
void	Wake ()
void	WakeAndMarkReady ()
Waker &	waker ()
void	MarkComplete ()
void	Unlist ()
	Removes this future from its list, if it is in one.
void	Reset ()
	Unlists the FutureCore and resets it to the empty state.
template<typename FutureType >
auto	DoPend (FutureType &future, Context &cx)
bool	in_list () const

Friends
class	BaseFutureList

Additional Inherited Members
Protected Member Functions inherited from pw::IntrusiveForwardList< T >::Item
constexpr	Item ()=default

Constructor & Destructor Documentation

FutureCore() [1/2]

constexpr pw::async2::FutureCore::FutureCore ( FutureState::Pending  )

inlineexplicitconstexpr

Constructs a pending FutureCore that represents an async operation. Pend must be called until it returns Ready.

A pending FutureCore must be tracked by its provider (e.g. in a FutureList).

FutureCore() [2/2]

constexpr pw::async2::FutureCore::FutureCore ( FutureState::ReadyForCompletion  )

inlineexplicitconstexpr

Creates a wakeable future that is ready for completion. The next call to Pend must return Ready.

Member Function Documentation

DoPend()

template<typename FutureType >

auto pw::async2::FutureCore::DoPend ( FutureType &  future, Context &  cx  )

inline

Optional Pend() function that defers to the future implementation's DoPend(Context&) function. FutureCore::DoPend does the following:

• Asserts that the future is pendable.
• If the future's DoPend returns Pending, stores a waker.
• If the future's DoPend returns Ready, marks the future as complete.

It is recommended for Pend to use FutureCore::DoPend, but not required. Custom Pend implementations must enforce the same semantics.

in_list()

bool pw::async2::FutureCore::in_list ( ) const

inline

Returns

whether the future is currently in a list.

is_complete()

constexpr bool pw::async2::FutureCore::is_complete ( ) const

inlineconstexpr

Returns

Whether the future has completed: the future's Pend() returned Ready.

is_initialized()

constexpr bool pw::async2::FutureCore::is_initialized ( ) const

inlineconstexpr

Returns

true if the future was NOT default constructed. The future either represents an active or completed asynchronous operation.

is_pendable()

constexpr bool pw::async2::FutureCore::is_pendable ( ) const

inlineconstexpr

Returns

Whether the future's Pend() function can be called.

is_ready()

constexpr bool pw::async2::FutureCore::is_ready ( ) const

inlineconstexpr

Returns

true if the next Pend() call is guaranteed to return Ready. Depending on the implementation, Pend() may return Ready while is_ready is false.

Future implementations call WakeAndMarkReady to set is_ready to true.

MarkComplete()

void pw::async2::FutureCore::MarkComplete ( )

inline

Mark the future as complete, which indicates that a future has returned Ready from its Pend function.

Warning

Do not use this function when FutureCore::DoPend is used. FutureCore::DoPend calls MarkComplete when Pend() returns Ready.

Wake()

void pw::async2::FutureCore::Wake ( )

inline

Wakes the task waiting on the future, if any. The future must be pended in order to make progress.

WakeAndMarkReady()

void pw::async2::FutureCore::WakeAndMarkReady ( )

inline

Wakes the task pending the future and sets is_ready to true. Only call this if the next call to to the future's Pend() will return Ready.

waker()

Waker & pw::async2::FutureCore::waker ( )

inline

Provides direct access to the waker for future implementations that manually store a waker.

Warning

Do not use this function when FutureCore::DoPend is used. FutureCore::DoPend stores the waker when Pend() returns Pending.

---

The documentation for this class was generated from the following file:

• pw_async2/public/pw_async2/future.h