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...

Classes
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...

using	CallbackType = std::function< void(const TaskBase &, ExceptionContainer &)>
	Type of a callback function which is invoked when a task has finished, failed or has been aborted. The function receives a reference to the task it originates from as well as a reference to a wrapper holding an exception which might have occurred while executing the task. More...

Public Member Functions
	TaskBase (CallbackType CallbackFunc=nullptr) noexcept
	Constructs an instrument task. More...

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

Thread-safe public functions
Methods can be called from any thread. Only atomic operations are performed.
TaskState	GetState () const noexcept
	Getter for the instrument task's current state. More...

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

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. More...

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

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. More...

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

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

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

bool	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()`. More...

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()`. More...

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

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

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. More...

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

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()`. More...

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 891 of file Instrument.h.

Member Typedef Documentation

◆ CallbackType

using DynExp::TaskBase::CallbackType = std::function<void(const TaskBase&, ExceptionContainer&)>

Type of a callback function which is invoked when a task has finished, failed or has been aborted. The function receives a reference to the task it originates from as well as a reference to a wrapper holding an exception which might have occurred while executing the task.

Definition at line 939 of file Instrument.h.

Member Enumeration Documentation

◆ TaskState

enum 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 948 of file Instrument.h.

Constructor & Destructor Documentation

◆ TaskBase()

DynExp::TaskBase::TaskBase ( CallbackType CallbackFunc = nullptr )

inlinenoexcept

Constructs an instrument task.

Parameters

CallbackFunc This callback function is called after the task has finished (either successfully or not) with a reference 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 979 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 442 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 1023 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 1016 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 997 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 1010 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 465 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 1064 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 473 of file Instrument.cpp.

◆ Run()

bool 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 true if task handling should continue, false if 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 481 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 true if task handling should continue, false if 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

const CallbackType DynExp::TaskBase::CallbackFunc

private

This callback function is called after the task has finished (either successfully or not) with a reference 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 1072 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 1079 of file Instrument.h.

◆ InstrumentBaseOnly

InstrumentBaseOnlyType DynExp::TaskBase::InstrumentBaseOnly

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

Definition at line 1026 of file Instrument.h.

◆ InstrumentDataBaseOnly

InstrumentDataBaseOnlyType DynExp::TaskBase::InstrumentDataBaseOnly

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

Definition at line 1027 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 1086 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 1078 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 Typedef Documentation

◆ CallbackType

Member Enumeration Documentation

◆ TaskState

Constructor & Destructor Documentation

◆ TaskBase()

◆ ~TaskBase()

Member Function Documentation

◆ Abort()

◆ GetErrorCode()

◆ GetState()

◆ IsAborting()

◆ IsLocked()

◆ KeepFinishedTask()

◆ Lock()

◆ Run()

◆ RunChild()

Member Data Documentation

◆ CallbackFunc

◆ ErrorCode

◆ InstrumentBaseOnly

◆ InstrumentDataBaseOnly

◆ ShouldAbort

◆ State