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_impl	Member function that is called once upon creation.
abort_impl	Member function that is called when the task is aborted.
finish_impl	Member function that is called when the task finished.
force_killed	Member function that is called when the task is killed.

See also: Example

#include <AIStatefulTask.h>

Inheritance diagram for AIStatefulTask:

[legend]

Collaboration diagram for AIStatefulTask:

[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

enum AIStatefulTask::base_state_type

protected

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

enum AIStatefulTask::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

debug Write 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

handler The 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

state A 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:

statefultask/AIStatefulTask.h
statefultask/AIStatefulTask.cxx

Detailed Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Friends

Member Enumeration Documentation

◆ base_state_type

◆ on_abort_st

Constructor & Destructor Documentation

◆ AIStatefulTask()

Member Function Documentation

◆ abort_impl()

◆ aborted()

◆ active()

◆ condition_str_impl()

◆ executing()

◆ finish_impl()

◆ finished()

◆ force_killed()

◆ getDuration()

◆ initialize_impl()

◆ is_immediate()

◆ multiplex_impl()

◆ running()

◆ state_str()

◆ state_str_impl()

◆ task_name()

◆ task_name_impl()

◆ waiting()

◆ waiting_or_aborting()