Example Class Reference

Detailed Description

An example task class.

Every stateful task is (indirectly) derived from AIStatefulTask.

For example:

class ExampleBase : public AIStatefulTask
{
  ...
};
 
class Example : public ExampleBase
{
 protected:
  // Each derived class must declare direct_base_type to be the class that it is directly derived from.
  using direct_base_type = ExampleBase;
 
  // Each derived class must define the states that it might go through.
  enum example_state_type {
    Example_start = direct_base_type::state_end,     // The first state must be equal to direct_base_type::state_end.
    Example_next,
    Example_foo,
    Example_done                                     // The last state is used to give state_end its value.
  };
 
 public:
  // Each derived class must define a state_end that is one beyond its last state.
  static constexpr state_type state_end = Example_done + 1;
 
 public:
  // The derived class must have a default constructor.
  Example();
 
 protected:
 // The destructor of the derived class must be protected.
  ~Example() override;
 
 protected:
   // The following two virtual functions must be implemented:
 
   // Convert a state_type to a human readable string, for debug purposes.
   char const* state_str_impl(state_type run_state) const override;
 
   // Actually run the task.
   void multiplex_impl(state_type run_state) override;
 
   // The following virtual functions may be overridden (they have a default):
 
   // Handle initializing the task object.
   // The default initialize_impl sets the starting state to AIStatefulTask::state_end,
   // which should be the first state of the derived class.
   void initialize_impl() override;
 
   // Handle aborting from current bs_multiplex state.
   // The default abort_impl does nothing.
   void abort_impl() override;
 
   // Handle cleaning up from initialization (or post abort) state.
   // The default finish_impl() does nothing.
   void finish_impl() override;
};

Inheritance diagram for Example:

Collaboration diagram for Example:

Protected Member Functions
char const *	condition_str_impl (condition_type run_state) const override
char const *	state_str_impl (state_type run_state) const override
void	initialize_impl () override
void	multiplex_impl (state_type run_state) override
void	abort_impl () override
void	finish_impl () override
void	force_killed () override
Protected Member Functions inherited from AIStatefulTask
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 *	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...

Additional Inherited Members
Public Types inherited from AIStatefulTask
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 inherited from AIStatefulTask
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 inherited from AIStatefulTask
static char const *	state_str (base_state_type state)
Static Public Attributes inherited from AIStatefulTask
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 inherited from AIStatefulTask
enum	base_state_type {   bs_reset , bs_initialize , bs_multiplex , bs_abort ,   bs_finish , bs_callback , bs_killed }
	The type of mState. More...

Member Function Documentation

abort_impl()

void Example::abort_impl ( )

overrideprotectedvirtual

Handle aborting the task.

Example implementation:

void Example::abort_impl()
{
}

Reimplemented from AIStatefulTask.

condition_str_impl()

char const * Example::condition_str_impl ( condition_type  run_state ) const

overrideprotectedvirtual

Stringify a condition, for debugging output.

Parameters

condition

A user defined condition.

Returns

A string literal with the human readable name of the condition.

This is a virtual function of the base class AIStatefulTask and should be overridden by every derived class.

Example implementation:

char const* Example::condition_str_impl(condition_type condition) const
{
  switch(condition)
  {
    // A complete listing of all condition_type bits defined by Example.
    AI_CASE_RETURN(foo_condition);
    // ...
    AI_CASE_RETURN(bar_condition);
  }
  return direct_base_type::condition_str_impl(condition);
}

Reimplemented from AIStatefulTask.

finish_impl()

void Example::finish_impl ( )

overrideprotectedvirtual

Handle finishing the task.

Example implementation:

void Example::finish_impl()
{
}

Reimplemented from AIStatefulTask.

force_killed()

void Example::force_killed ( )

overrideprotectedvirtual

Handle being force killed.

This member function is called when a task is running in an AIEngine and that engine is flushed (by calling AIEngine::flush()). The result is that the task just stops running cold. Neither abort_impl() nor finish_impl() is called: it just stops getting any CPU cycles and should be destructed shortly.

You probably will never to override this function. In fact, it will never be called unless you call AIEngine::flush() yourself and its main purpose is to avoid an assert in the destructor of the tasks (because otherwise their internal state would show they are still running which is an error otherwise).

Example implementation:

void Example::force_killed()
{
  direct_base_class::force_killed();
  // Handle being forcefully killed.
}

Reimplemented from AIStatefulTask.

initialize_impl()

void Example::initialize_impl ( )

overrideprotectedvirtual

Return a human readable name for the most derived class.

Returns

A string literal with the human readable name of the (most derived) task.

This is a virtual function of the base class AIStatefulTask and must be overridden by every derived class.

Example implementation:

   char const* Example::task_name_impl() const
   {
     return "Example";
   }
  /
char const* task_name_impl() const override;
 

Reimplemented from AIStatefulTask.

multiplex_impl()

void Example::multiplex_impl ( state_type  run_state )

overrideprotectedvirtual

The main implementation of the task. Run the task.

Parameters

run_state

The current user defined state that the task is in.

Example implementation:

void Example::multiplex_impl(state_type run_state)
{
  switch(run_state)
  {
    case Example_start:
      // Handle state Example_start here.
      break;
    case Example_next:
      // Handle state Example_next here.
      break;
    // ... etc.
    case Example_done:
      finish();
      break;
  }
}

Implements AIStatefulTask.

state_str_impl()

char const * Example::state_str_impl ( state_type  run_state ) const

overrideprotectedvirtual

Stringify a run state, for debugging output.

Parameters

run_state

A user defined state.

Returns

A string literal with the human readable name of the state.

This is a virtual function of the base class AIStatefulTask and must be overridden by every derived class.

Example implementation:

char const* Example::state_str_impl(state_type run_state) const
{
  // If this fails then a derived class forgot to add an AI_CASE_RETURN for this state.
  ASSERT(run_state < state_end);
  switch(run_state)
  {
    // A complete listing of hello_world_state_type.
    AI_CASE_RETURN(Example_start);
    // ...
    AI_CASE_RETURN(Example_done);
  }
  return direct_base_type::state_str_impl(run_state);
}

Reimplemented from AIStatefulTask.

---

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

• statefultask/AIStatefulTask.cxx