Pigweed
C/C++ API Reference
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Loading...
Searching...
No Matches
Public Member Functions | Private Member Functions | Friends | List of all members
pw::async2::Task Class Referenceabstract
Inheritance diagram for pw::async2::Task:
pw::containers::future::IntrusiveList< T >::Item 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 Member Functions

constexpr Task (log::Token name)
 
 Task (const Task &)=delete
 
 Task (Task &&)=delete
 
Taskoperator= (const Task &)=delete
 
Taskoperator= (Task &&)=delete
 
Poll Pend (Context &cx)
 
bool IsRegistered () const
 
void Deregister ()
 
void Destroy ()
 

Private Member Functions

virtual Poll DoPend (Context &)=0
 
virtual void DoDestroy ()
 

Friends

class Dispatcher
 
class Waker
 
class NativeDispatcherBase
 

Additional Inherited Members

- Protected Member Functions inherited from pw::containers::future::IntrusiveList< T >::Item
constexpr Item ()=default
 

Detailed Description

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:

Constructor & Destructor Documentation

◆ Task()

constexpr pw::async2::Task::Task ( log::Token  name)
inlineconstexpr

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")) {}
};
Definition: task.h:61
Provides basic helpers for reading and writing UTF-8 encoded strings.
Definition: alignment.h:27

Member 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.

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.

◆ Destroy()

void pw::async2::Task::Destroy ( )
inline

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.

◆ DoDestroy()

virtual void pw::async2::Task::DoDestroy ( )
inlineprivatevirtual

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.

Reimplemented in pw::async2::internal::AllocatedTask< Pendable >, and pw::async2::internal::RunHeapFuncTask< Func >.

◆ 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.

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

Implemented in pw::async2::internal::RunHeapFuncTask< Func >, pw::async2::internal::AllocatedTask< Pendable >, pw::async2::CoroOrElseTask, pw::async2::internal::PendableAsTaskWithOutput< Pendable >, pw::async2::PendFuncTask< Func >, and pw::async2::PendableAsTask< Pendable >.

◆ 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:

◆ 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.


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