Tasks

Overview

Logical collections of asynchronous work.

Learn more: Tasks

Submodules
	Context
	Resources for scheduling asynchronous work.

Classes
class	pw::async2::CallbackTask< FutureType, Func >
class	pw::async2::FuncTask< Func >
class	pw::async2::RunOnceTask< Func, ReturnValuePolicy >
class	pw::async2::RunOnceTask< Func, ReturnValuePolicy::kDiscard >
class	pw::async2::FutureTask< T >

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

Typedefs
using	pw::async2::Task::Context = ::pw::async2::Context

Enumerations
enum class	pw::async2::ReturnValuePolicy : bool { kKeep , kDiscard }
	Whether to store or discard the function's return value in RunOnceTask.

Functions
template<typename FutureType , typename Func >
	pw::async2::CallbackTask (Func &&, FutureType &&) -> CallbackTask< FutureType, Func >
template<typename Func >
	pw::async2::FuncTask (Func &&) -> FuncTask< std::decay_t< Func > >
template<typename Func >
	pw::async2::RunOnceTask (Func &&) -> RunOnceTask< Func >
template<typename T >
	pw::async2::FutureTask (T &&value) -> FutureTask< T >
	pw::async2::Context::Context (const Context &)=delete
	pw::async2::Context::Context (Context &&)=delete
Context &	pw::async2::Context::operator= (const Context &)=delete
Context &	pw::async2::Context::operator= (Context &&)=delete
void	pw::async2::Context::ReEnqueue ()
PendingType	pw::async2::Context::Unschedule ()
constexpr	pw::async2::Task::Task (log::Token name=kDefaultName)
	pw::async2::Task::Task (const Task &)=delete
	pw::async2::Task::Task (Task &&)=delete
Task &	pw::async2::Task::operator= (const Task &)=delete
Task &	pw::async2::Task::operator= (Task &&)=delete
virtual	pw::async2::Task::~Task ()
Poll	pw::async2::Task::Pend (Context &cx)
bool	pw::async2::Task::IsRegistered () const
void	pw::async2::Task::Deregister ()
void	pw::async2::Task::Join ()
virtual Poll	pw::async2::Task::DoPend (Context &)=0

Friends
class	pw::async2::Context::Task
class	pw::async2::Task::Dispatcher
class	pw::async2::Task::Waker

Typedef Documentation

Context

using pw::async2::Task::Context = ::pw::async2::Context

protected

Alias Context here so subclasses don't try to look up the private base. Do NOT use this alias directly (Task::Context); instead, use pw::async2::Context.

Function Documentation

Deregister()

void pw::async2::Task::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.

Deregister will not destroy the underlying Task.

Note

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

Warning

This method 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.

DoPend()

virtual Poll pw::async2::Task::DoPend ( Context &  )

privatepure virtual

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.

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

Implemented in pw::async2::RunOnceTask< Func, ReturnValuePolicy >, pw::async2::RunOnceTask< Func, ReturnValuePolicy::kDiscard >, pw::async2::CallbackTask< FutureType, Func >, pw::async2::CoroOrElseTask, pw::async2::CoroTask< T, policy >, pw::async2::CoroTask< T, ReturnValuePolicy::kDiscard >, pw::async2::FallibleCoroTask< T, AllocationErrorHandler, policy >, pw::async2::FallibleCoroTask< T, AllocationErrorHandler, ReturnValuePolicy::kDiscard >, pw::async2::FuncTask< Func >, and pw::async2::FutureTask< T >.

IsRegistered()

bool pw::async2::Task::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.

Join()

void pw::async2::Task::Join

(

)

Blocks this thread until the task finishes running.

Precondition

The task must be posted to a Dispatcher that runs in a different thread.

Pend()

Poll pw::async2::Task::Pend ( Context &  cx )

inline

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.

ReEnqueue()

void pw::async2::Context::ReEnqueue ( )

inline

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, ...);
waker.Wake();

Task()

constexpr pw::async2::Task::Task ( log::Token  name = kDefaultName )

inlineexplicitconstexpr

Creates a task with the specified name. To generate a name token, use the PW_ASYNC_TASK_NAME macro, e.g.

class MyTask : public pw::async2::Task {
  MyTask() : pw::async2::Task(PW_ASYNC_TASK_NAME("MyTask")) {}
};

Unschedule()

PendingType pw::async2::Context::Unschedule ( )

inline

Indicates that the task has not completed, but that it also does not need to register a waker and go to sleep. This results in the task being removed from the dispatcher, requiring it to be manually re-posted to run again.

~Task()

virtual pw::async2::Task::~Task ( )

virtual

The task must not be registered with a Dispatcher upon destruction. Tasks are deregistered automatically upon completion or Dispatcher destruction. This is necessary to ensure that neither the Dispatcher nor Waker reference the Task object after destruction.

The Task destructor cannot perform this deregistration. Other threads may be polling the task, and since the subclass destructor runs first, subclass state accessed by Pend would be invalidated before the base destructor could deregister the task.