AIStatefulTask ‐ Asynchronous, Stateful Task Scheduler library.

Threads-like task objects evolving through user-defined states.

Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Friends | List of all members
AIStatefulTask Class Referenceabstract

Detailed Description

Base class for task objects.

Derive a new task from this base class. The derived class must have a protected destructor that uses the override keyword.

Furthermore a derived class must define,

direct_base_type The immediate base class of the derived class.
foo_state_type An enum with the (additional) states of the task, where the first state must have the value direct_base_type::state_end.
state_end A static constexpr state_type with a value one larger than its largest state.
state_str_impl A member function that returns a char const* to a human readable string for each of its states (for debug purposes).
multiplex_impl The core function with a switch on the current state to be run.

And optionally override zero or more of the following virtual functions:

initialize_implMember function that is called once upon creation.
abort_implMember function that is called when the task is aborted.
finish_implMember function that is called when the task finished.
force_killedMember function that is called when the task is killed.
See also
Example

#include <AIStatefulTask.h>

Inheritance diagram for AIStatefulTask:
Inheritance graph
[legend]
Collaboration diagram for AIStatefulTask:
Collaboration graph
[legend]

Classes

struct  Actuation
 
struct  Conditions
 
struct  Handler
 

Public Types

enum  on_abort_st { abort_parent , signal_parent , do_nothing }
 What to do when a child task is aborted. More...
 
using state_type = uint32_t
 The type of run_state.
 
using condition_type = uint32_t
 The type of the skip_wait and idle bit masks.
 

Public Member Functions

Conditions print_conditions (condition_type conditions)
 
 AIStatefulTask (bool debug)
 
void run (Handler default_handler, std::function< void(bool)> cb_function)
 
void run (std::function< void(bool)> cb_function)
 The same as above but use the immediate Handler.
 
void run (Handler default_handler, AIStatefulTask *parent, condition_type condition, on_abort_st on_abort=abort_parent)
 
void run (AIStatefulTask *parent, condition_type condition, on_abort_st on_abort=abort_parent)
 
void run (Handler default_handler=Handler::immediate)
 
void kill ()
 
void abort ()
 
bool signal (condition_type condition)
 
bool running () const
 
bool waiting () const
 
bool waiting_or_aborting () const
 
bool active (Handler handler) const
 
bool is_immediate () const
 
bool finished () const
 
bool aborted () const
 
bool executing () const
 
duration_type getDuration () const
 
char const * task_name () const
 

Static Public Member Functions

static char const * state_str (base_state_type state)
 

Static Public Attributes

static constexpr condition_type slow_down_condition = 0x40000000
 
static constexpr condition_type thread_pool_full_condition = 0x80000000
 
static constexpr condition_type AND_conditions_mask = 0xf0000000
 
static constexpr condition_type OR_conditions_mask = 0x0fffffff
 
static constexpr state_type state_end = bs_killed + 1
 The next state value to use for derived classes.
 

Protected Types

enum  base_state_type {
  bs_reset , bs_initialize , bs_multiplex , bs_abort ,
  bs_finish , bs_callback , bs_killed
}
 The type of mState. More...
 

Protected Member Functions

virtual ~AIStatefulTask ()
 Destructor.
 
void set_state (state_type new_state)
 
void wait (condition_type conditions)
 
void wait_until (AIWaitConditionFunc const &wait_condition, condition_type conditions)
 
void wait_until (AIWaitConditionFunc const &wait_condition, condition_type conditions, state_type new_state)
 
void finish ()
 
utils::FuzzyBool is_self_locked (AIStatefulTaskMutex const &stateful_task_mutex, AIStatefulTaskMutexNode const *handle)
 
void yield ()
 
void target (Handler handler)
 
void yield (Handler handler)
 
void yield_frame (AIEngine *engine, unsigned int frames)
 
void yield_ms (AIEngine *engine, unsigned int ms)
 
bool yield_if_not (Handler handler)
 
virtual char const * condition_str_impl (condition_type condition) const
 Called to stringify a condition type for debugging output. More...
 
virtual char const * state_str_impl (state_type run_state) const
 Called to stringify a run state for debugging output. Must be overridden. More...
 
virtual char const * task_name_impl () const =0
 This can be used to get a human readable name of the most-derived class. It must be guaranteed to always return the same pointer value so it can be used with Tracy (for example). More...
 
virtual void initialize_impl ()
 Called for base state bs_initialize. More...
 
virtual void multiplex_impl (state_type run_state)=0
 Called for base state bs_multiplex. More...
 
virtual void abort_impl ()
 Called for base state bs_abort. More...
 
virtual void finish_impl ()
 Called for base state bs_finish. More...
 
virtual void force_killed ()
 Called from AIEngine::flush(). More...
 

Friends

class AIFriendOfStatefulTask
 
class AIEngine
 
std::ostream & operator<< (std::ostream &, Conditions)
 

Member Enumeration Documentation

◆ base_state_type

The type of mState.

Enumerator
bs_reset 

Idle state before run is called. Reference count is zero (except for a possible external boost::intrusive_ptr).

bs_initialize 

State after run and before/during initialize_impl.

bs_multiplex 

State after initialize_impl and before finish() or abort().

bs_abort 

State after abort() and leaving inside multiplex_impl (if there), and before abort_impl().

bs_finish 

State after finish() (assuming abort() isn't called) and leaving multiplex_impl (if there), or after abort_impl, and before finish_impl().

bs_callback 

State after finish_impl() and before the call back.

bs_killed 

State after the call back, or when aborted before being initialized.

◆ on_abort_st

What to do when a child task is aborted.

Enumerator
abort_parent 

Call abort() on the parent.

signal_parent 

Call signal(condition_type) on the parent anyway.

do_nothing 

Abort without notifying the parent task.

Constructor & Destructor Documentation

◆ AIStatefulTask()

AIStatefulTask::AIStatefulTask ( bool  debug)
inline

Constructor of base class AIStatefulTask.

The debug parameter only exists when CWDEBUG is defined.

The following parameter is only available in debug mode.

Parameters
debugWrite debug output for this task to dc::statefultask.

Member Function Documentation

◆ abort_impl()

void AIStatefulTask::abort_impl ( )
protectedvirtual

Called for base state bs_abort.

Reimplemented in Example, AITimer, and task::Broker< Task, Args >.

◆ aborted()

bool AIStatefulTask::aborted ( ) const
inline

Return true if this task was aborted.

This value is guaranteed to be valid (only) after the task finished.

◆ active()

bool AIStatefulTask::active ( Handler  handler) const
inline

Return true if we are added to the current engine.

Parameters
handlerThe handler that this task is supposed to run in.
Returns
True if this task is actually added to handler.

◆ condition_str_impl()

char const * AIStatefulTask::condition_str_impl ( condition_type  condition) const
protectedvirtual

Called to stringify a condition type for debugging output.

See example_task for a description of the virtual functions.

Reimplemented in Example.

◆ executing()

bool AIStatefulTask::executing ( ) const
inline

Return true if this thread is executing this task right now (aka, we're inside multiplex somewhere).

◆ finish_impl()

void AIStatefulTask::finish_impl ( )
protectedvirtual

Called for base state bs_finish.

Reimplemented in Example.

◆ finished()

bool AIStatefulTask::finished ( ) const
inline

Return true if the task finished.

If this function returns false then the callback (or call to abort() on the parent) is guaranteed still going to happen. If this function returns true then the callback might have happened or might still going to happen. Call aborted() to check if the task finished successfully if this function returns true (or just call that in the callback).

◆ force_killed()

void AIStatefulTask::force_killed ( )
protectedvirtual

Called from AIEngine::flush().

Reimplemented in Example.

◆ getDuration()

duration_type AIStatefulTask::getDuration ( ) const
inline

Return total time that this task has been running.

May only be called from the main thread.

◆ initialize_impl()

void AIStatefulTask::initialize_impl ( )
protectedvirtual

Called for base state bs_initialize.

Reimplemented in Example.

◆ is_immediate()

bool AIStatefulTask::is_immediate ( ) const
inline

Test if the current Handler is immediate.

Returns
True if this task is currently running in an immediate handler.
See also
Handler::is_immediate

◆ multiplex_impl()

virtual void AIStatefulTask::multiplex_impl ( state_type  run_state)
protectedpure virtual

Called for base state bs_multiplex.

Implemented in Example, AITimer, and task::Broker< Task, Args >.

◆ running()

bool AIStatefulTask::running ( ) const
inline

Return true if the derived class is running.

The task was initialized (after initialize_impl) and did not call finish() or abort() yet (before finish() or abort()).

When a task enters multiplex_impl it is guaranteed to be running.

◆ state_str()

char const * AIStatefulTask::state_str ( base_state_type  state)
static

Return stringified state, for debugging purposes.

Parameters
stateA base state.

◆ state_str_impl()

char const * AIStatefulTask::state_str_impl ( state_type  run_state) const
protectedvirtual

Called to stringify a run state for debugging output. Must be overridden.

Reimplemented in Example, AITimer, and task::Broker< Task, Args >.

◆ task_name()

char const * AIStatefulTask::task_name ( ) const
inline

Return human readable name of (most derived) task.

◆ task_name_impl()

virtual char const * AIStatefulTask::task_name_impl ( ) const
protectedpure virtual

This can be used to get a human readable name of the most-derived class. It must be guaranteed to always return the same pointer value so it can be used with Tracy (for example).

Implemented in AITimer, and task::Broker< Task, Args >.

◆ waiting()

bool AIStatefulTask::waiting ( ) const

Return true if the derived class is running and idle.

Running and idle since the last call to wait; if already having been woken up due to a call to signal(condition) then we're still waiting until we actually re-entered begin_loop.

◆ waiting_or_aborting()

bool AIStatefulTask::waiting_or_aborting ( ) const

Return true if the derived class is running and idle or already being aborted.

A task reached the state aborting after returning from initialize_impl or multiplex_impl that called abort(). Or when abort() is called from the outside while the task is idle (in which case we are in the state aborting directly after the call to abort()).

See also
waiting

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