pw_async

Oveview

Portable APIs for asynchronous code. Main docs: https://pigweed.dev/pw_async.

Classes
struct	pw::async::Context
	Contextual information provided by a Dispatcher to a running task. More...
class	pw::async::Dispatcher
class	pw::async::test::FakeDispatcherFixture
class	pw::async::FunctionDispatcher
class	pw::async::HeapDispatcher
class	pw::async::Task

Typedefs
using	pw::async::TaskFunction = Function< void(Context &, Status)>

Functions
virtual void	pw::async::Dispatcher::Post (Task &task)
virtual void	pw::async::Dispatcher::PostAfter (Task &task, chrono::SystemClock::duration delay)
virtual void	pw::async::Dispatcher::PostAt (Task &task, chrono::SystemClock::time_point time)=0
virtual bool	pw::async::Dispatcher::Cancel (Task &task)=0
FakeDispatcher &	pw::async::test::FakeDispatcherFixture::dispatcher ()
	Returns the FakeDispatcher that should be used for dependency injection.
chrono::SystemClock::time_point	pw::async::test::FakeDispatcherFixture::now ()
	Returns the current fake time.
bool	pw::async::test::FakeDispatcherFixture::RunUntilIdle ()
bool	pw::async::test::FakeDispatcherFixture::RunUntil (chrono::SystemClock::time_point end_time)
bool	pw::async::test::FakeDispatcherFixture::RunFor (chrono::SystemClock::duration duration)
virtual Status	pw::async::FunctionDispatcher::Post (TaskFunction &&task_func)
	Post dispatcher owned |task_func| function.
virtual Status	pw::async::FunctionDispatcher::PostAfter (TaskFunction &&task_func, chrono::SystemClock::duration delay)
	Post dispatcher owned |task_func| function to be run after |delay|.
virtual Status	pw::async::FunctionDispatcher::PostAt (TaskFunction &&task_func, chrono::SystemClock::time_point time)=0
	Post dispatcher owned |task_func| function to be run at |time|.
	pw::async::HeapDispatcher::HeapDispatcher (Dispatcher &dispatcher)
Status	pw::async::HeapDispatcher::PostAt (TaskFunction &&task_func, chrono::SystemClock::time_point time) override
	Post dispatcher owned |task_func| function to be run at |time|.
void	pw::async::HeapDispatcher::PostAt (Task &task, chrono::SystemClock::time_point time) override
bool	pw::async::HeapDispatcher::Cancel (Task &task) override
chrono::SystemClock::time_point	pw::async::HeapDispatcher::now () override
	Returns the current time.
	pw::async::Task::Task ()
	pw::async::Task::Task (TaskFunction &&f)
	Constructs a Task that calls f when executed on a Dispatcher.
	pw::async::Task::Task (const Task &)=delete
Task &	pw::async::Task::operator= (const Task &)=delete
	pw::async::Task::Task (Task &&)=delete
Task &	pw::async::Task::operator= (Task &&)=delete
void	pw::async::Task::set_function (TaskFunction &&f)
void	pw::async::Task::operator() (Context &ctx, Status status)
	Executes this task.
backend::NativeTask &	pw::async::Task::native_type ()
const backend::NativeTask &	pw::async::Task::native_type () const

Variables
Dispatcher *	pw::async::Context::dispatcher
	The Dispatcher running the current Task.
Task *	pw::async::Context::task
	The current Task being executed.

Typedef Documentation

TaskFunction

using pw::async::TaskFunction = typedef Function<void(Context&, Status)>

A TaskFunction is a unit of work that is wrapped by a Task and executed on a Dispatcher.

TaskFunctions take a Context as their first argument. Before executing a Task, the Dispatcher sets the pointer to itself and to the Task in Context.

TaskFunctions take a Status as their second argument. When a Task is running as normal, |status| is PW_STATUS_OK. If a Task will not be able to run as scheduled, the Dispatcher will still invoke the TaskFunction with |status| PW_STATUS_CANCELLED. This provides an opportunity to reclaim resources held by the Task.

A Task will not run as scheduled if, for example, it is still waiting when the Dispatcher shuts down.

Function Documentation

Cancel() [1/2]

bool pw::async::HeapDispatcher::Cancel ( Task &  task )

inlineoverridevirtual

Prevent a Posted task from starting.

Returns: true: the task was successfully canceled and will not be run by the dispatcher until Posted again. false: the task could not be cancelled because it either was not posted, already ran, or is currently running on the Dispatcher thread.

Implements pw::async::Dispatcher.

Cancel() [2/2]

virtual bool pw::async::Dispatcher::Cancel ( Task &  task )

pure virtual

Prevent a Posted task from starting.

Returns: true: the task was successfully canceled and will not be run by the dispatcher until Posted again. false: the task could not be cancelled because it either was not posted, already ran, or is currently running on the Dispatcher thread.

Implemented in pw::async::HeapDispatcher, and pw::async::BasicDispatcher.

native_type()

backend::NativeTask & pw::async::Task::native_type ( )

inline

Returns the inner NativeTask containing backend-specific state. Only Dispatcher backends or non-portable code should call these methods!

now()

chrono::SystemClock::time_point pw::async::HeapDispatcher::now ( )

inlineoverridevirtual

Returns the current time.

Implements pw::chrono::VirtualClock< SystemClock >.

Post()

virtual void pw::async::Dispatcher::Post ( Task &  task )

inlinevirtual

Post caller-owned |task| to be run on the dispatch loop.

Posted tasks execute in the order they are posted. This ensures that tasks can re-post themselves and yield in order to allow other tasks the opportunity to execute.

A given |task| must only be posted to a single Dispatcher.

Reimplemented in pw::async::FunctionDispatcher.

PostAfter()

virtual void pw::async::Dispatcher::PostAfter ( Task &  task, chrono::SystemClock::duration  delay  )

inlinevirtual

Post caller owned |task| to be run after |delay|.

If |task| was already posted to run at an earlier time (before |delay| would expire), |task| must be run at the earlier time, and |task| may also be run at the later time.

Reimplemented in pw::async::FunctionDispatcher.

PostAt() [1/4]

void pw::async::HeapDispatcher::PostAt ( Task &  task, chrono::SystemClock::time_point  time  )

inlineoverridevirtual

Post caller owned |task| to be run at |time|.

If |task| was already posted to run before |time|, |task| must be run at the earlier time, and |task| may also be run at the later time.

Implements pw::async::Dispatcher.

PostAt() [2/4]

virtual void pw::async::Dispatcher::PostAt ( Task &  task, chrono::SystemClock::time_point  time  )

pure virtual

Post caller owned |task| to be run at |time|.

If |task| was already posted to run before |time|, |task| must be run at the earlier time, and |task| may also be run at the later time.

Implemented in pw::async::HeapDispatcher, pw::async::BasicDispatcher, and pw::async::FunctionDispatcher.

PostAt() [3/4]

Status pw::async::HeapDispatcher::PostAt ( TaskFunction &&  task_func, chrono::SystemClock::time_point  time  )

overridevirtual

Post dispatcher owned |task_func| function to be run at |time|.

Implements pw::async::FunctionDispatcher.

PostAt() [4/4]

virtual Status pw::async::FunctionDispatcher::PostAt ( TaskFunction &&  task_func, chrono::SystemClock::time_point  time  )

pure virtual

Post dispatcher owned |task_func| function to be run at |time|.

Implemented in pw::async::HeapDispatcher.

RunFor()

bool pw::async::test::FakeDispatcherFixture::RunFor ( chrono::SystemClock::duration  duration )

inline

Dispatches all tasks with due times up to now() + duration, progressively advancing the fake clock. Returns true iff any tasks were invoked during the run.

RunUntil()

bool pw::async::test::FakeDispatcherFixture::RunUntil ( chrono::SystemClock::time_point  end_time )

inline

Dispatches all tasks with due times up to end_time, progressively advancing the fake clock. Returns true iff any tasks were invoked during the run.

RunUntilIdle()

bool pw::async::test::FakeDispatcherFixture::RunUntilIdle ( )

inline

Dispatches all tasks with due times up until now(). Returns true iff any tasks were invoked during the run.

set_function()

void pw::async::Task::set_function ( TaskFunction &&  f )

inline

Configure the TaskFunction after construction. This MUST NOT be called while this Task is pending in a Dispatcher.

Task()

pw::async::Task::Task ( )

inline

The default constructor creates a Task without a function. set_function() must be called before posting the Task.