Data structure to contain data which is synchronized in between different threads. This is needed since the instrument thread, the threads of different modules, as well as the main thread might access the instrument at the same time. Every class (indirectly) derived from class InstrumentBase must be accompanied by a instrument data class derived from InstrumentDataBase. InstrumentDataBase and derived classes contain data shared by the respective instrument, module and main threads. Data only used by the instrument itself should be private members of the instrument class. More...

#include <Instrument.h>

Inheritance diagram for DynExp::InstrumentDataBase:

Classes
struct	dispatch_tag
	Refer to ParamsBase::dispatch_tag. More...

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

class	InstrumenThreadOnlyType
	Allow exclusive access to some of `InstrumentDataBase's` private methods to the instrument thread `InstrumentThreadMain()`. More...

Public Types
using	TaskQueueType = std::list< std::unique_ptr< TaskBase > >
	Type of an instrument task queue owning the tasks within.

using	TaskQueueIteratorType = TaskQueueType::const_iterator
	Const iterator type to elements of `TaskQueueType`.

Public Member Functions
	InstrumentDataBase ()

virtual	~InstrumentDataBase ()

auto	GetLastUpdateTime () const
	Getter for LastUpdate.

bool	IsExceptionIndicated () const noexcept
	Getter for HasException. Only performs atomic operations. Hence, this instrument data instance does not need to be locked for this function call.

std::exception_ptr	GetException () const noexcept
	Getter for InstrumentDataBase::InstrumentException. If InstrumentDataBase::InstrumentException is nullptr and InstrumentDataBase::HasException is still true, returns a pointer to a Util::Exception instance.

Instrument task queue
Methods to access and manipulate the task queue belonging to the instrument which owns the respective `InstrumentDataBase's` instance
void	EnqueueTask (std::unique_ptr< TaskBase > &&Task)
	Enqueues a task at the back of an instrument's task queue and notifies the instrument about the new task.

void	EnqueuePriorityTask (std::unique_ptr< TaskBase > &&Task)
	Enqueues a task at the front of an instrument's task queue and notifies the instrument about the new task.

std::unique_ptr< TaskBase >	PopTaskFront ()
	Removes a task from the front of an instrument's task queue.

std::unique_ptr< TaskBase >	PopTaskBack ()
	Removes a task from the back of an instrument's task queue.

auto	GetTaskFront () noexcept
	Getter for first enqueued task.

auto	GetTaskBack () noexcept
	Getter for last enqueued task.

size_t	GetNumEnqueuedTasks () const noexcept
	Getter for the instrument task queue's length.

std::unique_ptr< TaskBase >	PopFinishedTask ()
	Removes a task from the front of an instrument's list of finished tasks.

size_t	GetNumFinishedTasks () const noexcept
	Getter for the length of the instrument's list of finished tasks.

bool	IsQueueClosed () const noexcept
	Determines whether the instrument task queue is closed.

Public Member Functions inherited from Util::INonCopyable
	INonCopyable (const INonCopyable &)=delete

INonCopyable &	operator= (const INonCopyable &)=delete

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

InstrumenThreadOnlyType	InstrumentThreadOnly
	Allow exclusive access to some of `InstrumentDataBase's` private methods to the instrument thread `InstrumentThreadMain()`.

Private Member Functions
void	EnqueueTask (std::unique_ptr< TaskBase > &&Task, bool CallFromInstrThread, bool NotifyReceiver)
	Enqueues a task at the back of an instrument's task queue and notifies the instrument about the new task.

void	EnqueuePriorityTask (std::unique_ptr< TaskBase > &&Task, bool CallFromInstrThread, bool NotifyReceiver)
	Enqueues a task at the front of an instrument's task queue and notifies the instrument about the new task.

void	RemoveTaskFromQueue (TaskQueueIteratorType &Task)
	Removes a task from the instrument's task queue and inserts it into the instrument's list of finished tasks if TaskBase::KeepFinishedTask() returns true.

void	RemoveAllTasks ()
	Clears the instrument's task queue.

void	RemoveAllTasksExceptFront ()
	Clears the instrument's task queue but keeps the front task (the task with highest priority which is handled next).

void	CloseQueue ()
	Clsoes the instrument's task queue setting QueueClosed to true.

Util::OneToOneNotifier &	GetNewTaskNotifier () noexcept
	Getter for NewTaskNotifier.

void	IndicateException () noexcept
	Indicates to the main thread that an exception has happened in the instrument thread. Only performs atomic operations. Hence, this instrument data instance does not need to be locked for this function call.

void	SetException (std::exception_ptr Exception) noexcept
	Setter for InstrumentException.

void	CheckError () const
	Throws InstrumentException if it is not nullptr using Util::ForwardException().

void	CheckQueueState (bool CallFromInstrThread) const
	Checks whether it is currently allowed to enqueue tasks into the instrument task queue.

Stopped instrument only
Must only be called when the instrument thread is not running.
void	Reset ()
	Resets the `InstrumentDataBase's` instance and calls ResetImpl(dispatch_tag<InstrumentDataBase>) subsequently.

virtual void	ResetImpl (dispatch_tag< InstrumentDataBase >)
	Refer to DynExp::InstrumentDataBase::Reset(). Using tag dispatch mechanism to ensure that `ResetImpl()` of every derived class gets called - starting from `InstrumentDataBase`, descending the inheritance hierarchy. Override in order to reset derived classes.

Private Attributes
TaskQueueType	TaskQueue
	FIFO task queue of the instrument owning this `InstrumentDataBase` instance.

TaskQueueType	FinishedTasks
	List of the instrument's finished tasks. Tasks are moved here from TaskQueue after completion.

bool	QueueClosed
	If set to true, no new tasks can be enqueued (useful if an instrument is e.g. stopped).

Util::OneToOneNotifier	NewTaskNotifier
	Used to notify the instrument thread about new tasks when enqueuing tasks into the task queue. This allows the instrument thread to sleep until new tasks have to be handled.

std::chrono::system_clock::time_point	LastUpdate
	Time point when the instrument thread called InstrumentBase::UpdateDataInternal() the last time.

std::atomic< bool >	HasException
	If set to true, indicates to the main thread that an exception has happened in the instrument thread. In that case, the exception is possibly stored in InstrumentException.

std::exception_ptr	InstrumentException
	Used to transfer exceptions from the instrument thread to the main thread. Stores the exception responsible for the error state if the instrument which owns the respective `InstrumentDataBase's` instance is in such an error state.

Additional Inherited Members
Protected Member Functions inherited from Util::ISynchronizedPointerLockable
	ISynchronizedPointerLockable ()

	~ISynchronizedPointerLockable ()
	Object should never be destroyed before completely unlocked.

Protected Member Functions inherited from Util::INonCopyable
constexpr	INonCopyable ()=default

	~INonCopyable ()=default

Detailed Description

Data structure to contain data which is synchronized in between different threads. This is needed since the instrument thread, the threads of different modules, as well as the main thread might access the instrument at the same time. Every class (indirectly) derived from class InstrumentBase must be accompanied by a instrument data class derived from InstrumentDataBase. InstrumentDataBase and derived classes contain data shared by the respective instrument, module and main threads. Data only used by the instrument itself should be private members of the instrument class.

Warning: For the same Object, always lock the mutex of the corresponding parameter class before the mutex of the corresponding data class (or only one of them).

Definition at line 134 of file Instrument.h.

Class Documentation

◆ DynExp::InstrumentDataBase::dispatch_tag

struct DynExp::InstrumentDataBase::dispatch_tag

template<typename>
struct DynExp::InstrumentDataBase::dispatch_tag< typename >

Refer to ParamsBase::dispatch_tag.

Template Parameters

Type	(derived from class `InstrumentDataBase`) to instantiate the dispatch tag template with.

Definition at line 146 of file Instrument.h.

Member Typedef Documentation

◆ TaskQueueIteratorType

using DynExp::InstrumentDataBase::TaskQueueIteratorType = TaskQueueType::const_iterator

Const iterator type to elements of TaskQueueType.

Definition at line 138 of file Instrument.h.

◆ TaskQueueType

using DynExp::InstrumentDataBase::TaskQueueType = std::list<std::unique_ptr<TaskBase> >

Type of an instrument task queue owning the tasks within.

Definition at line 137 of file Instrument.h.

Constructor & Destructor Documentation

◆ InstrumentDataBase()

DynExp::InstrumentDataBase::InstrumentDataBase ( )

inline

Definition at line 200 of file Instrument.h.

◆ ~InstrumentDataBase()

virtual DynExp::InstrumentDataBase::~InstrumentDataBase ( )

inlinevirtual

Definition at line 201 of file Instrument.h.

Member Function Documentation

◆ CheckError()

void DynExp::InstrumentDataBase::CheckError ( ) const

private

Throws InstrumentException if it is not nullptr using Util::ForwardException().

Definition at line 213 of file Instrument.cpp.

◆ CheckQueueState()

void DynExp::InstrumentDataBase::CheckQueueState ( bool CallFromInstrThread ) const

private

Checks whether it is currently allowed to enqueue tasks into the instrument task queue.

Parameters

CallFromInstrThread Pass true if the instrument itself enqueues a task.

Exceptions

Util::InvalidStateException is thrown if the instrument task queue is closed and CallFromInstrThread is false.

Definition at line 218 of file Instrument.cpp.

◆ CloseQueue()

void DynExp::InstrumentDataBase::CloseQueue ( )

inlineprivate

Clsoes the instrument's task queue setting QueueClosed to true.

Definition at line 345 of file Instrument.h.

◆ EnqueuePriorityTask() [1/2]

void DynExp::InstrumentDataBase::EnqueuePriorityTask ( std::unique_ptr< TaskBase > && Task )

inline

Enqueues a task at the front of an instrument's task queue and notifies the instrument about the new task.

Parameters

Task	Task to enqueue, the queue takes ownership of the task.

Definition at line 221 of file Instrument.h.

◆ EnqueuePriorityTask() [2/2]

void DynExp::InstrumentDataBase::EnqueuePriorityTask	(	std::unique_ptr< TaskBase > &&	Task,
		bool	CallFromInstrThread,
		bool	NotifyReceiver
	)

private

Enqueues a task at the front of an instrument's task queue and notifies the instrument about the new task.

Parameters

Task	Task to enqueue, the queue takes ownership of the task.
CallFromInstrThread	Pass true if the instrument itself enqueues a task. This argument is forwarded to `CheckQueueState()`.
NotifyReceiver	Determines whether the instrument thread is notified that a new task has been enqueued. This is e.g. not desired when enqueuing update tasks in InstrumentBase::UpdateData().

Definition at line 163 of file Instrument.cpp.

◆ EnqueueTask() [1/2]

void DynExp::InstrumentDataBase::EnqueueTask ( std::unique_ptr< TaskBase > && Task )

inline

Enqueues a task at the back of an instrument's task queue and notifies the instrument about the new task.

Parameters

Task	Task to enqueue, the queue takes ownership of the task.

Definition at line 214 of file Instrument.h.

◆ EnqueueTask() [2/2]

void DynExp::InstrumentDataBase::EnqueueTask	(	std::unique_ptr< TaskBase > &&	Task,
		bool	CallFromInstrThread,
		bool	NotifyReceiver
	)

private

Enqueues a task at the back of an instrument's task queue and notifies the instrument about the new task.

Parameters

Task	Task to enqueue, the queue takes ownership of the task.
CallFromInstrThread	Pass true if the instrument itself enqueues a task. This argument is forwarded to `CheckQueueState()`.
NotifyReceiver	Determines whether the instrument thread is notified that a new task has been enqueued. This is e.g. not desired when enqueuing update tasks in InstrumentBase::UpdateData().

Definition at line 153 of file Instrument.cpp.

◆ GetException()

std::exception_ptr DynExp::InstrumentDataBase::GetException ( ) const

noexcept

Getter for InstrumentDataBase::InstrumentException. If InstrumentDataBase::InstrumentException is nullptr and InstrumentDataBase::HasException is still true, returns a pointer to a Util::Exception instance.

Returns: Returns the exception being responsible for the instrument's current state.

Definition at line 145 of file Instrument.cpp.

◆ GetLastUpdateTime()

auto DynExp::InstrumentDataBase::GetLastUpdateTime ( ) const

inline

Getter for LastUpdate.

Returns: Returns the time point when the instrument issued a task to update its data last.

Definition at line 284 of file Instrument.h.

◆ GetNewTaskNotifier()

Util::OneToOneNotifier & DynExp::InstrumentDataBase::GetNewTaskNotifier ( )

inlineprivatenoexcept

Getter for NewTaskNotifier.

Returns: Returns NewTaskNotifier to notify the instrument thread about new tasks.

Definition at line 351 of file Instrument.h.

◆ GetNumEnqueuedTasks()

size_t DynExp::InstrumentDataBase::GetNumEnqueuedTasks ( ) const

inlinenoexcept

Getter for the instrument task queue's length.

Returns: Returns the number of enqueued tasks.

Definition at line 257 of file Instrument.h.

◆ GetNumFinishedTasks()

size_t DynExp::InstrumentDataBase::GetNumFinishedTasks ( ) const

inlinenoexcept

Getter for the length of the instrument's list of finished tasks.

Returns: Returns the number of finished tasks.

Definition at line 271 of file Instrument.h.

◆ GetTaskBack()

auto DynExp::InstrumentDataBase::GetTaskBack ( )

inlinenoexcept

Getter for last enqueued task.

Returns: Returns an iterator to the instrument task queue's end.

Definition at line 251 of file Instrument.h.

◆ GetTaskFront()

auto DynExp::InstrumentDataBase::GetTaskFront ( )

inlinenoexcept

Getter for first enqueued task.

Returns: Returns an iterator to the instrument task queue's beginning.

Definition at line 245 of file Instrument.h.

◆ IndicateException()

void DynExp::InstrumentDataBase::IndicateException ( )

inlineprivatenoexcept

Indicates to the main thread that an exception has happened in the instrument thread. Only performs atomic operations. Hence, this instrument data instance does not need to be locked for this function call.

Definition at line 376 of file Instrument.h.

◆ IsExceptionIndicated()

bool DynExp::InstrumentDataBase::IsExceptionIndicated ( ) const

inlinenoexcept

Getter for HasException. Only performs atomic operations. Hence, this instrument data instance does not need to be locked for this function call.

Definition at line 290 of file Instrument.h.

◆ IsQueueClosed()

bool DynExp::InstrumentDataBase::IsQueueClosed ( ) const

inlinenoexcept

Determines whether the instrument task queue is closed.

Returns: Returns QueueClosed.

Definition at line 277 of file Instrument.h.

◆ PopFinishedTask()

std::unique_ptr< TaskBase > DynExp::InstrumentDataBase::PopFinishedTask ( )

Removes a task from the front of an instrument's list of finished tasks.

Returns: Returns the task releasing ownership of it. Returns nullptr if the list is empty.

Definition at line 134 of file Instrument.cpp.

◆ PopTaskBack()

std::unique_ptr< TaskBase > DynExp::InstrumentDataBase::PopTaskBack ( )

Removes a task from the back of an instrument's task queue.

Returns: Returns the task releasing ownership of it. Returns nullptr if the queue is empty.

Exceptions

Util::InvalidStateException is thrown if the task to be removed is locked. Refer to TaskBase::TaskState.

Definition at line 120 of file Instrument.cpp.

◆ PopTaskFront()

std::unique_ptr< TaskBase > DynExp::InstrumentDataBase::PopTaskFront ( )

Removes a task from the front of an instrument's task queue.

Returns: Returns the task releasing ownership of it. Returns nullptr if the queue is empty.

Exceptions

Util::InvalidStateException is thrown if the task to be removed is locked. Refer to TaskBase::TaskState.

Definition at line 106 of file Instrument.cpp.

◆ RemoveAllTasks()

void DynExp::InstrumentDataBase::RemoveAllTasks ( )

private

Clears the instrument's task queue.

Definition at line 181 of file Instrument.cpp.

◆ RemoveAllTasksExceptFront()

void DynExp::InstrumentDataBase::RemoveAllTasksExceptFront ( )

private

Clears the instrument's task queue but keeps the front task (the task with highest priority which is handled next).

Definition at line 186 of file Instrument.cpp.

◆ RemoveTaskFromQueue()

void DynExp::InstrumentDataBase::RemoveTaskFromQueue ( TaskQueueIteratorType & Task )

private

Removes a task from the instrument's task queue and inserts it into the instrument's list of finished tasks if TaskBase::KeepFinishedTask() returns true.

Parameters

Task	Iterator to an enqueued task.

Definition at line 173 of file Instrument.cpp.

◆ Reset()

void DynExp::InstrumentDataBase::Reset ( )

private

Resets the InstrumentDataBase's instance and calls ResetImpl(dispatch_tag<InstrumentDataBase>) subsequently.

Definition at line 194 of file Instrument.cpp.

◆ ResetImpl()

virtual void DynExp::InstrumentDataBase::ResetImpl ( dispatch_tag< InstrumentDataBase > )

inlineprivatevirtual

Refer to DynExp::InstrumentDataBase::Reset(). Using tag dispatch mechanism to ensure that ResetImpl() of every derived class gets called - starting from InstrumentDataBase, descending the inheritance hierarchy. Override in order to reset derived classes.

Reimplemented in DynExpInstr::InterModuleCommunicatorData.

Definition at line 368 of file Instrument.h.

◆ SetException()

void DynExp::InstrumentDataBase::SetException ( std::exception_ptr Exception )

privatenoexcept

Setter for InstrumentException.

Parameters

Exception Exception to store.

Definition at line 206 of file Instrument.cpp.

Member Data Documentation

◆ FinishedTasks

TaskQueueType DynExp::InstrumentDataBase::FinishedTasks

private

List of the instrument's finished tasks. Tasks are moved here from TaskQueue after completion.

Definition at line 399 of file Instrument.h.

◆ HasException

std::atomic<bool> DynExp::InstrumentDataBase::HasException

private

If set to true, indicates to the main thread that an exception has happened in the instrument thread. In that case, the exception is possibly stored in InstrumentException.

Definition at line 416 of file Instrument.h.

◆ InstrumentBaseOnly

InstrumentBaseOnlyType DynExp::InstrumentDataBase::InstrumentBaseOnly

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

Definition at line 300 of file Instrument.h.

◆ InstrumentException

std::exception_ptr DynExp::InstrumentDataBase::InstrumentException

private

Used to transfer exceptions from the instrument thread to the main thread. Stores the exception responsible for the error state if the instrument which owns the respective InstrumentDataBase's instance is in such an error state.

Definition at line 423 of file Instrument.h.

◆ InstrumentThreadOnly

InstrumenThreadOnlyType DynExp::InstrumentDataBase::InstrumentThreadOnly

Allow exclusive access to some of InstrumentDataBase's private methods to the instrument thread InstrumentThreadMain().

Definition at line 301 of file Instrument.h.

◆ LastUpdate

std::chrono::system_clock::time_point DynExp::InstrumentDataBase::LastUpdate

private

Time point when the instrument thread called InstrumentBase::UpdateDataInternal() the last time.

Definition at line 409 of file Instrument.h.

◆ NewTaskNotifier

Util::OneToOneNotifier DynExp::InstrumentDataBase::NewTaskNotifier

private

Used to notify the instrument thread about new tasks when enqueuing tasks into the task queue. This allows the instrument thread to sleep until new tasks have to be handled.

Definition at line 407 of file Instrument.h.

◆ QueueClosed

bool DynExp::InstrumentDataBase::QueueClosed

private

If set to true, no new tasks can be enqueued (useful if an instrument is e.g. stopped).

Definition at line 400 of file Instrument.h.

◆ TaskQueue

TaskQueueType DynExp::InstrumentDataBase::TaskQueue

private

FIFO task queue of the instrument owning this InstrumentDataBase instance.

Definition at line 398 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

Additional Inherited Members

Detailed Description

Class Documentation

◆ DynExp::InstrumentDataBase::dispatch_tag

Member Typedef Documentation

◆ TaskQueueIteratorType

◆ TaskQueueType

Constructor & Destructor Documentation

◆ InstrumentDataBase()

◆ ~InstrumentDataBase()

Member Function Documentation

◆ CheckError()

◆ CheckQueueState()

◆ CloseQueue()

◆ EnqueuePriorityTask() [1/2]

◆ EnqueuePriorityTask() [2/2]

◆ EnqueueTask() [1/2]

◆ EnqueueTask() [2/2]

◆ GetException()

◆ GetLastUpdateTime()

◆ GetNewTaskNotifier()

◆ GetNumEnqueuedTasks()

◆ GetNumFinishedTasks()

◆ GetTaskBack()

◆ GetTaskFront()

◆ IndicateException()

◆ IsExceptionIndicated()

◆ IsQueueClosed()

◆ PopFinishedTask()

◆ PopTaskBack()

◆ PopTaskFront()

◆ RemoveAllTasks()

◆ RemoveAllTasksExceptFront()

◆ RemoveTaskFromQueue()

◆ Reset()

◆ ResetImpl()

◆ SetException()

Member Data Documentation

◆ FinishedTasks

◆ HasException

◆ InstrumentBaseOnly

◆ InstrumentException

◆ InstrumentThreadOnly

◆ LastUpdate

◆ NewTaskNotifier

◆ QueueClosed

◆ TaskQueue