pw::async2::Dispatcher Class Reference

Overview

A single-threaded cooperatively scheduled runtime for async tasks.

Dispatcher implementations must pop and run tasks with one of the following:

• PopAndRunAllReadyTasks() – Runs tasks until no progress can be made. The dispatcher will be woken when a task is ready to run.
• PopTaskToRun() and RunTask() – Run tasks individually. Dispatcher implementations MUST pop and run tasks until PopTaskToRun() returns nullptr. The dispatcher will not be woken when a task becomes ready unless PopTaskToRun() has returned nullptr.
• PopSingleTaskForThisWake() and RunTask() – Run tasks individually. It PopSingleTaskForThisWake is intended for use then only a single task (or one final task) should be executed. Is not necessary to call PopSingleTaskForThisWake() until it returns nullptr. Each call can result in one potentially redundant DoWake() call, so PopTaskToRun should be used one multiple tasks are executed.

Inheritance diagram for pw::async2::Dispatcher:

Public Member Functions
	Dispatcher (Dispatcher &)=delete
Dispatcher &	operator= (Dispatcher &)=delete
	Dispatcher (Dispatcher &&)=delete
Dispatcher &	operator= (Dispatcher &&)=delete
void	Post (Task &task)
void	LogRegisteredTasks ()

Protected Types
enum	RunTaskResult { kActive = Task::kActive , kDeregistered = Task::kDeregistered , kCompleted = Task::kCompleted }

Protected Member Functions
bool	PopAndRunAllReadyTasks ()
Task *	PopTaskToRun ()
Task *	PopTaskToRun (bool &has_posted_tasks)
Task *	PopSingleTaskForThisWake ()
RunTaskResult	RunTask (Task &task)

Private Member Functions
virtual void	DoWake ()=0

Friends
class	Task
class	Waker
template<typename >
class	DispatcherForTestFacade

Member Enumeration Documentation

RunTaskResult

enum pw::async2::Dispatcher::RunTaskResult

protected

Result from Dispatcher::RunTask. Reports the state of the task when it finished running.

Enumerator
kActive	The task is still posted to the dispatcher.
kDeregistered	The task was removed from the dispatcher by another thread.
kCompleted	The task finished running.

Member Function Documentation

DoWake()

virtual void pw::async2::Dispatcher::DoWake ( )

privatepure virtual

Sends a wakeup signal to this Dispatcher.

This method's implementation must ensure that the Dispatcher runs at some point in the future.

DoWake() will only be called once until one of the following occurs:

• PopAndRunAllReadyTasks() is called,
• PopTaskToRun() returns nullptr, or
• PopSingleTaskForThisWake() is called.

Note

The internal::lock() may or may not be held here, so it must not be acquired by DoWake, nor may DoWake assume that it has been acquired.

Implemented in pw::async2::BasicDispatcher, pw::async2::DispatcherForTestFacade< Native >, and pw::async2::EpollDispatcher.

LogRegisteredTasks()

void pw::async2::Dispatcher::LogRegisteredTasks

(

)

Outputs log statements about the tasks currently registered with this dispatcher.

PopAndRunAllReadyTasks()

bool pw::async2::Dispatcher::PopAndRunAllReadyTasks ( )

protected

Pops and runs tasks until there are no tasks ready to run.

This function may be called by dispatcher implementations to run tasks. This is a high-level function that runs all ready tasks without logging or metrics. For more control, use PopTaskToRun and RunTask.

Return values

true	The dispatcher has posted tasks, but they are sleeping.
false	The dispatcher has no posted tasks.

PopSingleTaskForThisWake()

Task * pw::async2::Dispatcher::PopSingleTaskForThisWake ( )

inlineprotected

Pop a single task to run. Each call to PopSingleTaskForThisWake can result in up to one DoWake() call, so use PopTaskToRun or PopAndRunAllReadyTasks to run multiple tasks.

PopTaskToRun() [1/2]

Task * pw::async2::Dispatcher::PopTaskToRun ( )

inlineprotected

Pops a task and marks it as running. The task must be passed to RunTask.

PopTaskToRun MUST be called repeatedly until it returns nullptr, at which point the dispatcher will request a wake.

PopTaskToRun() [2/2]

Task * pw::async2::Dispatcher::PopTaskToRun ( bool &  has_posted_tasks )

inlineprotected

PopTaskToRun overload that optionally reports the whether the Dispatcher has registered tasks. This allows callers to distinguish between there being no woken tasks and no posted tasks at all.

Like the no-argument overload, PopTaskToRun MUST be called repeatedly until it returns nullptr.

Parameters

[out]

has_posted_tasks

Set to true if the dispatcher has at least one task posted, potentially including the task that was popped. Set to false if the dispatcher has no posted tasks.

Returns

A pointer to a task that is ready to run, or nullptr if there are no ready tasks.

Post()

void pw::async2::Dispatcher::Post

(

Task &

task

)

Tells the Dispatcher to run Task to completion. This method does not block.

After Post is called, Task::Pend will be invoked once. If Task::Pend does not complete, the Dispatcher will wait until the Task is "awoken", at which point it will call Pend again until the Task completes.

This method is thread-safe and interrupt-safe.

RunTask()

RunTaskResult pw::async2::Dispatcher::RunTask ( Task &  task )

protected

Runs the task that was returned from PopTaskToRun.

Warning

Do NOT access the Task object after RunTask returns! The task could have destroyed, either by the dispatcher or another thread, even if RunTask returns kActive. It is only safe to access a popped task before calling RunTask, since it is marked as running and will not be destroyed until after it runs.

---

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

• pw_async2/public/pw_async2/dispatcher.h