AIStatefulTask ‐ Asynchronous, Stateful Task Scheduler library.

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

Functions
Yield and engine control
Collaboration diagram for Yield and engine control:

Functions

void AIStatefulTask::yield ()
 
void AIStatefulTask::target (Handler handler)
 
void AIStatefulTask::yield (Handler handler)
 
void AIStatefulTask::yield_frame (AIEngine *engine, unsigned int frames)
 
void AIStatefulTask::yield_ms (AIEngine *engine, unsigned int ms)
 
bool AIStatefulTask::yield_if_not (Handler handler)
 

Detailed Description

A call to yield*() has basically no effect on a task, except that its execution is delayed a bit: this causes the task to return to the AIEngine main loop code. That way other running tasks (in that engine) will get the chance to execute before the current task is continued.

Note that if a state calls yield*() without calling first set_state then this might still cause 100% cpu usage despite the call to yield* if the task runs in an engine without max_duration because the task will rapidly execute again and then call yield* over and over: an engine without max_duration keeps iterating over its tasks until all tasks finished. Otherwise the engine will return from AIEngine::mainloop regardless after at least AIEngine::sMaxDuration milliseconds have passed (which can be set by calling AIEngine::setMaxDuration(milliseconds)).

Function Documentation

◆ target()

void AIStatefulTask::target ( Handler  handler)
protected

Continue running from engine.

The task will keep running in this engine until target is called again. Call target(Handler::idle) to return to running freely (with a default engine, etc, if one was given).

Parameters
handlerThe required engine or thread pool queue to run in, or Handler::idle to turn the target off.

◆ yield() [1/2]

void AIStatefulTask::yield ( )
protected

Yield to give CPU to other tasks, but do not block.

If a task runs potentially too long, it is a good idea to regularly call this member function and break out of multiplex_impl in order not to let other tasks in the same engine starve.

◆ yield() [2/2]

void AIStatefulTask::yield ( Handler  handler)
protected

The above two combined.

Parameters
handlerThe required engine or thread pool queue to run in.

◆ yield_frame()

void AIStatefulTask::yield_frame ( AIEngine engine,
unsigned int  frames 
)
protected

Switch to engine and sleep for frames frames.

This function can only be used for an engine with a max_duration. One frame means one entry into AIEngine::mainloop. So, for frames entries of mainloop this task will not be run.

Parameters
engineThe engine to sleep in. This must be an engine with a max_duration set.
framesThe number frames to run other tasks (if any) before running this task again.

◆ yield_if_not()

bool AIStatefulTask::yield_if_not ( Handler  handler)
protected

Do not really yield, unless the current engine is not engine.

Parameters
handlerThe required engine or thread pool queue to run in.
Returns
true if it switched engine.

◆ yield_ms()

void AIStatefulTask::yield_ms ( AIEngine engine,
unsigned int  ms 
)
protected

Switch to engine and sleep for ms milliseconds.

This function can only be used for an engine with a max_duration.

Parameters
engineThe engine to sleep in. This must be an engine with a max_duration set.
msThe number of miliseconds to run other tasks (if any) before running this task again.