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.

auto	GetException () const noexcept
	Getter for InstrumentDataBase::InstrumentException.

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

◆ ~InstrumentDataBase()

virtual DynExp::InstrumentDataBase::~InstrumentDataBase ( )

inlinevirtual

Definition at line 200 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 189 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 194 of file Instrument.cpp.

◆ CloseQueue()

void DynExp::InstrumentDataBase::CloseQueue ( )

inlineprivate

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

Definition at line 336 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 220 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 147 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 213 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 137 of file Instrument.cpp.

◆ GetException()

auto DynExp::InstrumentDataBase::GetException ( ) const

inlinenoexcept

Getter for InstrumentDataBase::InstrumentException.

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

Definition at line 289 of file Instrument.h.

◆ 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 283 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 342 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 256 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 270 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 250 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 244 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 276 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 126 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 112 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 98 of file Instrument.cpp.

◆ RemoveAllTasks()

void DynExp::InstrumentDataBase::RemoveAllTasks ( )

private

Clears the instrument's task queue.

Definition at line 165 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 170 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 157 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 178 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 359 of file Instrument.h.

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

◆ InstrumentBaseOnly

InstrumentBaseOnlyType DynExp::InstrumentDataBase::InstrumentBaseOnly

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

Definition at line 291 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 394 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 292 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 387 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 385 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 378 of file Instrument.h.

◆ TaskQueue

TaskQueueType DynExp::InstrumentDataBase::TaskQueue

private

FIFO task queue of the instrument owning this InstrumentDataBase instance.

Definition at line 376 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()

◆ IsQueueClosed()

◆ PopFinishedTask()

◆ PopTaskBack()

◆ PopTaskFront()

◆ RemoveAllTasks()

◆ RemoveAllTasksExceptFront()

◆ RemoveTaskFromQueue()

◆ Reset()

◆ ResetImpl()

Member Data Documentation

◆ FinishedTasks

◆ InstrumentBaseOnly

◆ InstrumentException

◆ InstrumentThreadOnly

◆ LastUpdate

◆ NewTaskNotifier

◆ QueueClosed

◆ TaskQueue