Base class for all tasks being processed by instruments. The class must not contain public virtual functions since TaskBase::CallbackFunc could call them in TaskBase's destructor. More...

#include <Instrument.h>

Classes
class	CallbackType
	Type owning a callback function which is invoked when a task has finished, failed, or has been aborted. It is ensured that the callback function is invoked latest upon destruction of the respective `CallbackType` instance. A callback function can only be invoked once through a `CallbackType` instance. More...

class	InstrumentBaseOnlyType
	Allow exclusive access to some of `TaskBase's` private methods to `InstrumentBase`. More...

class	InstrumentDataBaseOnlyType
	Allow exclusive access to some of `TaskBase's` private methods to `InstrumentDataBase`. More...

Public Types
enum class	TaskState { Waiting , Locked , Running , Finished , Failed , Aborted }
	Defines states an instrument's task can undergo. Possible state transitions are: More...

Public Member Functions
	TaskBase (CallbackType CallbackFunc=nullptr, std::chrono::system_clock::time_point DeferUntil={}) noexcept
	Constructs an instrument task.

	TaskBase (TaskBase &Other, std::chrono::system_clock::time_point DeferUntil={}) noexcept
	Constructs an instrument task, moving CallbackFunc from another task to this task. The other task is left with a CallbackFunc that will not be executed anymore after this operation. Using this constructor is useful, if a running task enqueues (an)other task(s). In this case, the callback function should not be called by the original task but by the last task in this chain of tasks.

virtual	~TaskBase ()=0
	The destructor aborts a waiting task setting State to TaskState::Aborted. Then, it calls CallbackFunc with a default-constructed `ExceptionContainer` instance.

Thread-safe public functions
Methods can be called from any thread. Only atomic operations are performed.
auto	GetDeferUntil () const noexcept
	Getter for the instrument task's earliest execution time point.

TaskState	GetState () const noexcept
	Getter for the instrument task's current state.

bool	IsLocked () const noexcept
	Determines whether the task is locked.

bool	IsAborting () const noexcept
	Determines whether the task should abort. A derived task is encouraged to call this method before performing any action or in between the individual steps of a more complex action.

int	GetErrorCode () const noexcept
	Getter for the error code related to an error possibly occurred while the task was executed.

void	Abort ()
	Requests the task to abort. There is no guarantee that the derived task does call `IsAborting()` to check whether it should abort. The task could have finished already or the implementation of `RunChild()` in the derived class does not allow for aborting.

Public Attributes
InstrumentBaseOnlyType	InstrumentBaseOnly
	Allow exclusive access to some of `TaskBase's` private methods to `InstrumentBase`.

InstrumentDataBaseOnlyType	InstrumentDataBaseOnly
	Allow exclusive access to some of `TaskBase's` private methods to `InstrumentDataBase`.

Private Member Functions
void	Lock ()
	Locks the task to prepare it for execution.

InstrumentBase::TaskHandlingContinuationType	Run (InstrumentInstance &Instance)
	Runs the task. Override `RunChild()` to define a derived task's action(s). Any exception leaving `RunChild()` will terminate the instrument thread. In this case, the instrument has to be reset in order to restart it. For minor errors occurring in `RunChild()`, return a `TaskResultType` instance with TaskResultType::ErrorCode set to an appropriate (non-zero) value. This sets State to TaskState::Failed. Note that in this case there might be no way to retrieve the error if finished tasks are not kept (i.e. `KeepFinishedTask()` returns false) and if no CallbackFunc has been set. `RunChild()` is supposed to check the return value of `IsAborting()`.

Override
Override by derived classes.
virtual TaskResultType	RunChild (InstrumentInstance &Instance)=0
	Runs the task. Override `RunChild()` to define a derived task's action(s). Any exception leaving `RunChild()` will terminate the instrument thread. In this case, the instrument has to be reset in order to restart it. For minor errors occurring in `RunChild()`, return a `TaskResultType` instance with TaskResultType::ErrorCode set to an appropriate (non-zero) value. This sets State to TaskState::Failed. Note that in this case there might be no way to retrieve the error if finished tasks are not kept (i.e. `KeepFinishedTask()` returns false) and if no CallbackFunc has been set. `RunChild()` is supposed to check the return value of `IsAborting()`.

virtual bool	KeepFinishedTask () const noexcept
	Determines whether the task should be kept to check its results after execution. InstrumentDataBase::RemoveTaskFromQueue().

Private Attributes
CallbackType	CallbackFunc
	This callback function is called after the task has finished (either successfully or not) with a pointer to the current task and with a reference to the exception which occurred during the task execution (if an exception has occurred).

const std::chrono::system_clock::time_point	DeferUntil
	The execution of this task is deferred until the specified point in time is reached if `time_since_epoch()` of DeferUntil is non-zero. Tasks being deferred block the task queue of the instrument they are assigned to, i.e., other enqueued tasks do not run before this task to maintain the task order.

Instrument-to-other communication
These variables are for communication from the instrument thread to other thread(s) only.
std::atomic< TaskState >	State
	Holds the task's current state. Refer to TaskBase::TaskState.

std::atomic< int >	ErrorCode
	Holds the error code of an error which occurred during execution of the task function.

Other-to-instrument communication
These variables are for communication from other thread(s) to the instrument thread only.
std::atomic< bool >	ShouldAbort
	Indicates whether the task should abort. Refer to `Abort()` and `IsAborting()`.

Detailed Description

Base class for all tasks being processed by instruments. The class must not contain public virtual functions since TaskBase::CallbackFunc could call them in TaskBase's destructor.

Definition at line 928 of file Instrument.h.

Member Enumeration Documentation

◆ TaskState

enum class DynExp::TaskBase::TaskState

strong

Defines states an instrument's task can undergo. Possible state transitions are:

Waiting -> Locked/Running/Aborted
Locked -> Running
Running -> Finished/Failed/Aborted

Enumerator
Waiting	The task is enqueued and waiting for execution. This is the starting state after construction.
Locked	The task is locked since its execution is being prepared. It will be the next task to be executed.
Running	The task is currently being executed.
Finished	The task execution has finished. No error has occurred.
Failed	The task execution has failed due to an exception leaving `RunChild()`.
Aborted	The task has been aborted either by `~TaskBase()` or by returning a `TaskResultType` instance with TaskResultType::Aborted set to TaskResultType::AbortedType::Aborted from `RunChild()`.

Definition at line 1051 of file Instrument.h.

Constructor & Destructor Documentation

◆ TaskBase() [1/2]

DynExp::TaskBase::TaskBase	(	CallbackType	CallbackFunc = `nullptr`,
		std::chrono::system_clock::time_point	DeferUntil = `{}`
	)

inlinenoexcept

Constructs an instrument task.

Parameters

CallbackFunc This callback function is called after the task has finished (either successfully or not) with a pointer to the current task and with a reference to the exception which occurred during the task execution (if an exception has occurred).

DeferUntil The execution of this task is deferred until the specified point in time is reached if time_since_epoch() of DeferUntil is non-zero. Tasks being deferred block the task queue of the instrument they are assigned to, i.e., other enqueued tasks do not run before this task to maintain the task order. If the task does not support being deferred, the DeferUntil parameter is not available in the task's constructor.

Definition at line 1084 of file Instrument.h.

◆ TaskBase() [2/2]

DynExp::TaskBase::TaskBase	(	TaskBase &	Other,
		std::chrono::system_clock::time_point	DeferUntil = `{}`
	)

inlinenoexcept

Constructs an instrument task, moving CallbackFunc from another task to this task. The other task is left with a CallbackFunc that will not be executed anymore after this operation. Using this constructor is useful, if a running task enqueues (an)other task(s). In this case, the callback function should not be called by the original task but by the last task in this chain of tasks.

Parameters

Other	Other task to steal CallbackFunc from.
DeferUntil	The execution of this task is deferred until the specified point in time is reached if `time_since_epoch()` of DeferUntil is non-zero. Tasks being deferred block the task queue of the instrument they are assigned to, i.e., other enqueued tasks do not run before this task to maintain the task order.

Definition at line 1097 of file Instrument.h.

◆ ~TaskBase()

DynExp::TaskBase::~TaskBase ( )

pure virtual

The destructor aborts a waiting task setting State to TaskState::Aborted. Then, it calls CallbackFunc with a default-constructed ExceptionContainer instance.

Definition at line 516 of file Instrument.cpp.

Member Function Documentation

◆ Abort()

void DynExp::TaskBase::Abort ( )

inline

Requests the task to abort. There is no guarantee that the derived task does call IsAborting() to check whether it should abort. The task could have finished already or the implementation of RunChild() in the derived class does not allow for aborting.

Definition at line 1146 of file Instrument.h.

◆ GetDeferUntil()

auto DynExp::TaskBase::GetDeferUntil ( ) const

inlinenoexcept

Getter for the instrument task's earliest execution time point.

Returns: Returns DeferUntil.

Definition at line 1114 of file Instrument.h.

◆ GetErrorCode()

int DynExp::TaskBase::GetErrorCode ( ) const

inlinenoexcept

Getter for the error code related to an error possibly occurred while the task was executed.

Returns: Returns ErrorCode.

Definition at line 1139 of file Instrument.h.

◆ GetState()

TaskState DynExp::TaskBase::GetState ( ) const

inlinenoexcept

Getter for the instrument task's current state.

Returns: Returns State.

Definition at line 1120 of file Instrument.h.

◆ IsAborting()

bool DynExp::TaskBase::IsAborting ( ) const

inlinenoexcept

Determines whether the task should abort. A derived task is encouraged to call this method before performing any action or in between the individual steps of a more complex action.

Returns: Returns ShouldAbort.

Definition at line 1133 of file Instrument.h.

◆ IsLocked()

bool DynExp::TaskBase::IsLocked ( ) const

noexcept

Determines whether the task is locked.

Returns: Returns true if the task is in the state TaskState::Locked or TaskState::Running, false otherwise.

Definition at line 536 of file Instrument.cpp.

◆ KeepFinishedTask()

virtual bool DynExp::TaskBase::KeepFinishedTask ( ) const

inlineprivatevirtualnoexcept

Determines whether the task should be kept to check its results after execution. InstrumentDataBase::RemoveTaskFromQueue().

Returns: Return true to append the task to InstrumentDataBase::FinishedTasks after execution. Return false to destroy the task directly after execution.

Definition at line 1187 of file Instrument.h.

◆ Lock()

void DynExp::TaskBase::Lock ( )

private

Locks the task to prepare it for execution.

Exceptions

Util::InvalidStateException is thrown if the task is not in the TaskState::Waiting state.

Definition at line 544 of file Instrument.cpp.

◆ Run()

InstrumentBase::TaskHandlingContinuationType DynExp::TaskBase::Run ( InstrumentInstance & Instance )

private

Runs the task. Override RunChild() to define a derived task's action(s). Any exception leaving RunChild() will terminate the instrument thread. In this case, the instrument has to be reset in order to restart it. For minor errors occurring in RunChild(), return a TaskResultType instance with TaskResultType::ErrorCode set to an appropriate (non-zero) value. This sets State to TaskState::Failed. Note that in this case there might be no way to retrieve the error if finished tasks are not kept (i.e. KeepFinishedTask() returns false) and if no CallbackFunc has been set. RunChild() is supposed to check the return value of IsAborting().

Parameters

Instance Handle to the instrument thread's data

Returns: Returns whether task handling should continue or whether the instrument thread should terminate.

Exceptions

Util::InvalidStateException is thrown if the task is not in the TaskState::Waiting or TaskState::Locked state.

Definition at line 552 of file Instrument.cpp.

◆ RunChild()

virtual TaskResultType DynExp::TaskBase::RunChild ( InstrumentInstance & Instance )

privatepure virtual

Runs the task. Override RunChild() to define a derived task's action(s). Any exception leaving RunChild() will terminate the instrument thread. In this case, the instrument has to be reset in order to restart it. For minor errors occurring in RunChild(), return a TaskResultType instance with TaskResultType::ErrorCode set to an appropriate (non-zero) value. This sets State to TaskState::Failed. Note that in this case there might be no way to retrieve the error if finished tasks are not kept (i.e. KeepFinishedTask() returns false) and if no CallbackFunc has been set. RunChild() is supposed to check the return value of IsAborting().

Parameters

Instance Handle to the instrument thread's data

Returns: Returns whether task handling should continue or whether the instrument thread should terminate.

Exceptions

Util::InvalidStateException is thrown if the task is not in the TaskState::Waiting or TaskState::Locked state.

Member Data Documentation

◆ CallbackFunc

CallbackType DynExp::TaskBase::CallbackFunc

private

This callback function is called after the task has finished (either successfully or not) with a pointer to the current task and with a reference to the exception which occurred during the task execution (if an exception has occurred).

Definition at line 1195 of file Instrument.h.

◆ DeferUntil

const std::chrono::system_clock::time_point DynExp::TaskBase::DeferUntil

private

The execution of this task is deferred until the specified point in time is reached if time_since_epoch() of DeferUntil is non-zero. Tasks being deferred block the task queue of the instrument they are assigned to, i.e., other enqueued tasks do not run before this task to maintain the task order.

Definition at line 1203 of file Instrument.h.

◆ ErrorCode

std::atomic<int> DynExp::TaskBase::ErrorCode

private

Holds the error code of an error which occurred during execution of the task function.

Definition at line 1210 of file Instrument.h.

◆ InstrumentBaseOnly

InstrumentBaseOnlyType DynExp::TaskBase::InstrumentBaseOnly

Allow exclusive access to some of TaskBase's private methods to InstrumentBase.

Definition at line 1149 of file Instrument.h.

◆ InstrumentDataBaseOnly

InstrumentDataBaseOnlyType DynExp::TaskBase::InstrumentDataBaseOnly

Allow exclusive access to some of TaskBase's private methods to InstrumentDataBase.

Definition at line 1150 of file Instrument.h.

◆ ShouldAbort

std::atomic<bool> DynExp::TaskBase::ShouldAbort

private

Indicates whether the task should abort. Refer to Abort() and IsAborting().

Definition at line 1217 of file Instrument.h.

◆ State

std::atomic<TaskState> DynExp::TaskBase::State

private

Holds the task's current state. Refer to TaskBase::TaskState.

Definition at line 1209 of file Instrument.h.

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

Classes

Public Types

Public Member Functions

Public Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ TaskState

Constructor & Destructor Documentation

◆ TaskBase() [1/2]

◆ TaskBase() [2/2]

◆ ~TaskBase()

Member Function Documentation

◆ Abort()

◆ GetDeferUntil()

◆ GetErrorCode()

◆ GetState()

◆ IsAborting()

◆ IsLocked()

◆ KeepFinishedTask()

◆ Lock()

◆ Run()

◆ RunChild()

Member Data Documentation

◆ CallbackFunc

◆ DeferUntil

◆ ErrorCode

◆ InstrumentBaseOnly

◆ InstrumentDataBaseOnly

◆ ShouldAbort

◆ State