Reference#

pw_async2: Cooperative async tasks for embedded

C++ API reference#

class Task#

A task which may complete one or more asynchronous operations.

The Task interface is commonly implemented by users wishing to schedule work on an asynchronous Dispatcher. To do this, users may subclass Task, providing an implementation of the DoPend method which advances the state of the Task as far as possible before yielding back to the Dispatcher.

This process works similarly to cooperatively-scheduled green threads or coroutines, with a Task representing a single logical “thread” of execution. Unlike some green thread or coroutine implementations, Task does not imply a separately-allocated stack: Task state is most commonly stored in fields of the Task subclass.

Once defined by a user, Task s may be run by passing them to a Dispatcher via Dispatcher::Post. The Dispatcher will then Pend the Task every time that the Task indicates it is able to make progress.

Note that Task objects must not be destroyed while they are actively being Pend’d by a Dispatcher. To protect against this, be sure to do one of the following:

Use dynamic lifetimes by creating Task objects that continue to live until they receive a DoDestroy call.
Create Task objects whose stack-based lifetimes outlive their associated Dispatcher.
Call Deregister on the Task prior to its destruction. NOTE that Deregister may not be called from inside the Task’s own Pend method.

Subclassed by pw::async2::CoroOrElseTask, pw::async2::PendFuncTask< Func >, pw::async2::PendableAsTask< Pendable >, pw::async2::internal::AllocatedTask< Pendable >, pw::async2::internal::PendableAsTaskWithOutput< Pendable >, pw::async2::internal::RunHeapFuncTask< Func >

Public Functions

inline Poll Pend(Context &cx)#

A public interface for DoPend.

DoPend is normally invoked by a Dispatcher after a Task has been Post ed.

This wrapper should only be called by Task s delegating to other Task s. For example, a class MainTask might have separate fields for TaskA and TaskB, and could invoke Pend on these types within its own DoPend implementation.

bool IsRegistered() const#

Whether or not the Task is registered with a Dispatcher.

Returns true after this Task is passed to Dispatcher::Post until one of the following occurs:

This Task returns Ready from its Pend method.
Task::Deregister is called.
The associated Dispatcher is destroyed.

void Deregister()#

Deregisters this Task from the linked Dispatcher and any associated Waker values.

This must not be invoked from inside this task’s Pend function, as this will result in a deadlock.

NOTE: If this task’s Pend method is currently being run on the dispatcher, this method will block until Pend completes.

NOTE: This method sadly cannot guard against the dispatcher itself being destroyed, so this method must not be called concurrently with destruction of the dispatcher associated with this Task.

Note that this will not destroy the underlying Task.

inline void Destroy()#

A public interface for DoDestroy.

DoDestroy is normally invoked by a Dispatcher after a Post ed Task has completed.

This should only be called by Task s delegating to other Task s.

Private Functions

bool TryDeregister()#

Attempts to deregister this task.

If the task is currently running, this will return false and the task will not be deregistered.

virtual Poll DoPend(Context&) = 0#

Attempts to advance this Task to completion.

This method should not perform synchronous waiting, as doing so may block the main Dispatcher loop and prevent other Task s from progressing. Because of this, Task s should not invoke blocking Dispatcher methods such as RunUntilComplete.

Task s should also avoid invoking RunUntilStalled` on their own Dispatcher``.

Returns Ready if complete, or Pending if the Task was not yet able to complete.

If Pending is returned, the Task must ensure it is woken up when it is able to make progress. To do this, Task::Pend must arrange for Waker::Wake to be called, either by storing a copy of the Waker away to be awoken by another system (such as an interrupt handler).

inline virtual void DoDestroy()#

Performs any necessary cleanup of Task memory after completion.

This may include calls to std::destroy_at(this), and may involve deallocating the memory for this Task itself.

Tasks implementations which wish to be reused may skip self-destruction here.

template<typename T = ReadyType> class Poll#

A value that may or may not be ready yet.

Poll<T> most commonly appears as the return type of an function that checks the current status of an asynchronous operation. If the operation has completed, it returns with Ready(value). Otherwise, it returns Pending to indicate that the operations has not yet completed, and the caller should try again in the future.

Poll<T> itself is “plain old data” and does not change on its own. To check the current status of an operation, the caller must invoke the Poll<T> returning function again and examine the newly returned Poll<T>.

Public Functions

Poll() = delete#: Basic constructors.

template<typename U, internal_poll::EnableIfImplicitlyConvertible<T, const U&> = 0> inline constexpr Poll( const Poll<U> &other, )#

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.

inline constexpr bool IsReady() const noexcept#: Returns whether or not this value is Ready.

inline constexpr bool IsPending() const noexcept#: Returns whether or not this value is Pending.

inline constexpr Poll Readiness() const noexcept#: Returns a Poll<> without the inner value whose readiness matches that of this.

inline constexpr T &value() & noexcept#

Returns the inner value.

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

inline constexpr const T *operator->() const noexcept#

Accesses the inner value.

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

inline constexpr const T &operator*() const & noexcept#

Returns the inner value.

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

inline constexpr void IgnorePoll() const#

Ignores the Poll value.

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

inline 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)#: Returns a value indicating completion with some result (constructed in-place).

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

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

class Context#

Context for an asynchronous Task.

This object contains resources needed for scheduling asynchronous work, such as the current Dispatcher and the Waker for the current task.

Context s are most often created by Dispatcher s, which pass them into Task::Pend.

Public Functions

inline Context(Dispatcher &dispatcher, Waker &waker)#: Creates a new Context containing the currently-running Dispatcher and a Waker for the current Task.

inline Dispatcher &dispatcher()#

The Dispatcher on which the current Task is executing.

This can be used for spawning new tasks using dispatcher().Post(task);.

void ReEnqueue()#

Queues the current Task::Pend to run again in the future, possibly after other work is performed.

This may be used by Task implementations that wish to provide additional fairness by yielding to the dispatch loop rather than perform too much work in a single iteration.

This is semantically equivalent to calling:

Waker waker;
PW_ASYNC_STORE_WAKER(cx, waker, ...);
std::move(waker).Wake();

void InternalStoreWaker(Waker &waker_out)#

INTERNAL-ONLY: users should use the PW_ASYNC_STORE_WAKER macro instead.

Saves a Waker into waker_out which, when awoken, will cause the current task to be Pend’d by its dispatcher.

class Waker#

An object which can respond to asynchronous events by queueing work to be done in response, such as placing a Task on a Dispatcher loop.

Waker s are often held by I/O objects, custom concurrency primitives, or interrupt handlers. Once the thing the Task was waiting for is available, Wake should be called so that the Task is alerted and may process the event.

Waker s may be held for any lifetime, and will be automatically nullified when the underlying Dispatcher or Task is deleted.

Waker s are most commonly created by Dispatcher s, which pass them into Task::Pend via its Context argument.

Public Functions

Waker &operator=(Waker &&other) noexcept#

Replace this Waker with another.