Pigweed
 
Loading...
Searching...
No Matches
Public Member Functions | List of all members
pw::async::Dispatcher Class Referenceabstract

#include <dispatcher.h>

Inheritance diagram for pw::async::Dispatcher:
pw::chrono::VirtualClock< SystemClock > pw::async::BasicDispatcher pw::async::FunctionDispatcher pw::async::HeapDispatcher

Public Member Functions

virtual void Post (Task &task)
 
virtual void PostAfter (Task &task, chrono::SystemClock::duration delay)
 
virtual void PostAt (Task &task, chrono::SystemClock::time_point time)=0
 
virtual bool Cancel (Task &task)=0
 
- Public Member Functions inherited from pw::chrono::VirtualClock< SystemClock >
virtual SystemClock::time_point now ()=0
 Returns the current time.
 

Additional Inherited Members

- Static Public Member Functions inherited from pw::chrono::VirtualClock< SystemClock >
static VirtualClock< SystemClock > & RealClock ()
 Returns a reference to the real system clock to aid instantiation.
 

Detailed Description

Abstract base class for an asynchronous dispatcher loop.

Dispatchers run many short, non-blocking units of work on a single thread. This approach has a number of advantages compared with executing concurrent tasks on separate threads:

  • Dispatchers can make more efficient use of system resources, since they don't need to maintain separate thread stacks.
  • Dispatchers can run on systems without thread support, such as no-RTOS embedded environments.
  • Dispatchers allow tasks to communicate with one another without the synchronization overhead of locks, atomics, fences, or volatile.

Thread support: Dispatcher methods may be safely invoked from any thread, but the resulting tasks will always execute on a single thread. Whether or not methods may be invoked from interrupt context is implementation-defined.

VirtualSystemClock: Dispatcher implements VirtualSystemClock in order to provide a consistent source of (possibly mocked) time information to tasks.

A simple default dispatcher implementation is provided by pw_async_basic.

Member Function Documentation

◆ Cancel()

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.

◆ 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()

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.

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