Base class for instruments. Instruments comprise virtual devices (meta instruments) and physial devices (instruments). While meta instruments are used by modules (ModuleBase) as an abstraction layer, physical instruments derive from meta instruments and make usually use of one hardware adapter (HardwareAdapterBase) to communicate with the underlying hardware. More...

Inheritance diagram for DynExp::InstrumentBase:

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

Public Types
using	ParamsType = InstrumentParamsBase
	Type of the parameter class belonging to this `Object` type. Declare this alias in every derived class with the respective parameter class accompanying the derived `Object`. More...

using	ConfigType = InstrumentConfiguratorBase
	Type of the configurator class belonging to this `Object` type. Declare this alias in every derived class with the respective configurator class accompanying the derived `Object`. More...

using	InstrumentDataType = InstrumentDataBase
	Type of the data class belonging to this `InstrumentBase` type. Declare this alias in every derived class with the respective data class accompanying the derived `InstrumentBase`. More...

using	InstrumentDataTypeSyncPtrType = Util::SynchronizedPointer< InstrumentDataType >
	Alias for the return type of InstrumentBase::GetInstrumentData(). Data class instances wrapped into Util::SynchronizedPointer can be accessed in a thread-safe way. More...

using	InstrumentDataTypeSyncPtrConstType = Util::SynchronizedPointer< const InstrumentDataType >
	Alias for the return type of InstrumentBase::GetInstrumentData() const. Data class instances wrapped into Util::SynchronizedPointer can be accessed in a thread-safe way. More...

gRPC aliases
Redefine in derived meta instrument classes to use them in DynExpInstr::gRPCInstrument.
using	InitTaskType = InitTaskBase
	Defines a task for initializing an instrument within an instrument inheritance hierarchy. Each instrument (indirectly) derived from class `InstrumentBase` must be accompanied by an initialization task class derived from `InitTaskBase`. Even if the task does not do anything, at least it has to call InitTaskBase::InitFuncImpl() of the derived instrument's initialization task class. More...

using	ExitTaskType = ExitTaskBase
	Defines a task for deinitializing an instrument within an instrument inheritance hierarchy. Each instrument (indirectly) derived from class `InstrumentBase` must be accompanied by a deinitialization task class derived from `ExitTaskBase`. Even if the task does not do anything, at least it has to call ExitTaskBase::ExitFuncImpl() of the derived instrument's deinitialization task class. More...

using	UpdateTaskType = UpdateTaskBase
	Defines a task for updating an instrument within an instrument inheritance hierarchy. Each instrument (indirectly) derived from class `InstrumentBase` must be accompanied by an update task class derived from `UpdateTaskBase`. Even if the task does not do anything, at least it has to call UpdateTaskBase::UpdateFuncImpl() of the derived instrument's update task class. More...

Public Types inherited from DynExp::RunnableObject
using	ParamsType = RunnableObjectParams
	Type of the parameter class belonging to this `Object` type. Declare this alias in every derived class with the respective parameter class accompanying the derived `Object`. More...

using	ConfigType = RunnableObjectConfigurator
	Type of the configurator class belonging to this `Object` type. Declare this alias in every derived class with the respective configurator class accompanying the derived `Object`. More...

Public Types inherited from DynExp::Object
using	ParamsType = ParamsBase
	Type of the parameter class belonging to this `Object` type. Declare this alias in every derived class with the respective parameter class accompanying the derived `Object`. More...

using	ParamsTypeSyncPtrType = Util::SynchronizedPointer< ParamsType >
	Alias for the return type of Object::GetParams(). Parameters wrapped into Util::SynchronizedPointer can be accessed in a thread-safe way. More...

using	ParamsConstTypeSyncPtrType = Util::SynchronizedPointer< const ParamsType >
	Alias for the return type of Object::GetParams() const. Parameters wrapped into Util::SynchronizedPointer can be accessed in a thread-safe way. More...

using	ConfigType = ConfiguratorBase
	Type of the configurator class belonging to this `Object` type. Declare this alias in every derived class with the respective configurator class accompanying the derived `Object`. More...

using	ParamsGetterType = Util::CallableMemberWrapper< Object, decltype(&Object::GetParams)>
	Invoking an instance of this alias is supposed to call Object::GetParams() of the instance the Util::CallableMemberWrapper has been constructed with. More...

Public Member Functions
	InstrumentBase (const std::thread::id OwnerThreadID, ParamsBasePtrType &&Params)
	Constructs an instrument instance. More...

virtual	~InstrumentBase ()=0

virtual std::string	GetCategory () const override
	Returns the category of this `Object` type. More...

template<typename DerivedInstrT , typename... TaskFuncArgTs, typename... ArgTs>
ExceptionContainer	AsSyncTask (void(DerivedInstrT::*TaskFunc)(TaskFuncArgTs...) const, ArgTs &&...Args) const
	Calls a (derived) instrument's function which inserts a task into the instrument's task queue synchronously. This means that `AsSyncTask()` blocks until the task has been executed or aborted. This is achieved by passing a callback function to the task which in turn sets a flag after the task execution. The thread calling `AsSyncTask()` blocks (via `std::this_thread::yield()`) until this flag is set. More...

Public Member Functions inherited from DynExp::RunnableObject
	RunnableObject (const std::thread::id OwnerThreadID, ParamsBasePtrType &&Params)
	Constructs an `Object` instance. More...

virtual	~RunnableObject ()=0

void	SetPaused (bool Pause, std::string Description="")
	Pauses or resumes a `RunnableObject` instance. Its thread stays running, but the instance does not perform any action while it is paused. More...

bool	IsRunning () const noexcept
	Returns Running. More...

bool	IsPaused () const noexcept
	Returns Paused. More...

bool	IsExiting () const noexcept
	Returns ShouldExit. More...

auto	GetStartupType () const noexcept
	Returns Startup. More...

auto	GetReasonWhyPaused () const
	Returns ReasonWhyPaused. More...

bool	Run (QWidget *ParentWidget=nullptr)
	Starts the `RunnableObject` instance's thread and ensures that all `Object` instances linked to this instance via `ObjectLink` parameters are in a ready state. Calls `RunChild()` which is to be overridden by derived classes to start a thread and to pass this thread back by calling `StoreThread()`. More...

bool	RunIfRunAutomatic ()
	Calls `Run()` if RunnableObjectParams::Startup is set to RunnableObjectParams::Automatic. More...

bool	RunIfRunOnCreation ()
	Calls `Run()` if RunnableObjectParams::Startup is set to RunnableObjectParams::OnCreation. More...

void	Terminate (bool Force=false, const std::chrono::milliseconds Timeout=TerminateTimeoutDefault)
	Notifies the `RunnableObject` instance's thread to terminate and waits until it has ended. Calls TerminateImpl(). More...

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

INonCopyable &	operator= (const INonCopyable &)=delete

Public Member Functions inherited from DynExp::Object
ItemIDType	GetID () const noexcept
	Returns the ID of this `Object` instance. Thread-safe since ID is const. More...

std::string	GetCategoryAndName () const
	Builds a string from an `Object's` category and name to allow the user to identify an `Object's` type. More...

void	EnsureReadyState (bool IsAutomaticStartup)
	Ensures that this `Object` instance is ready by possibly starting its worker thread or by opening connections to hardware devices. More...

void	CheckLinkedObjectStates () const
	Checks whether `Object` instances this instance uses are in a ready state. Override `CheckLinkedObjectStatesChild()` to implement this behavior. More...

void	Reset ()
	Resets this `Object` instance (including all its derived classes) by calling `ResetImpl()`. A reset implies that the derived classes reload all their parameters from Params and that all `LinkedObjectWrapper` instances owned by this `Object` instance become invalidated. More...

void	BlockIfUnused (const std::chrono::milliseconds Timeout=Util::ILockable::DefaultTimeout)
	Blocks this `Object` instance setting Object::IsBlocked to true. Refer to Object::IsBlocked for the consequences. More...

ParamsConstTypeSyncPtrType	GetParams (const std::chrono::milliseconds Timeout=GetParamsTimeoutDefault) const
	Locks the mutex of the parameter class instance Params assigned to this `Object` instance and returns a pointer to the locked Params. More...

ParamsTypeSyncPtrType	GetParams (const std::chrono::milliseconds Timeout=GetParamsTimeoutDefault)
	Locks the mutex of the parameter class instance Params assigned to this `Object` instance and returns a pointer to the locked Params. More...

auto	GetObjectName (const std::chrono::milliseconds Timeout=GetParamsTimeoutDefault) const
	Returns the name of this `Object` instance. More...

bool	IsSharedUsageEnabled (const std::chrono::milliseconds Timeout=GetParamsTimeoutDefault) const
	Returns whether shared usage has been enabled for this `Object` instance. Refer to ParamsBase::UsageType. More...

void	SetWarning (std::string Description, int ErrorCode) const
	Setter for Object::Warning. Sets the warning by a description and an error code. More...

void	SetWarning (const Util::Exception &e) const
	Setter for Object::Warning. Sets the warning by retrieving the warning data from an exception `e`. More...

void	ClearWarning () const
	Resets Object::Warning. More...

auto	GetWarning () const
	Returns Object::Warning in a thread-safe way by copying its internal data. More...

std::exception_ptr	GetException (const std::chrono::milliseconds Timeout=Util::ILockable::DefaultTimeout) const
	Returns a pointer to the exception which has caused this `Object` instance to fail. More...

bool	IsReady () const
	Returns wheter this `Object` instance is ready (e.g. it is running or connected to a hardware device) and not blocked (refer to Object::IsBlocked). More...

auto	GetUseCount (const std::chrono::milliseconds Timeout=Util::ILockable::DefaultTimeout) const
	Counts the registered useres in a thread-safe way. More...

bool	IsUnused (const std::chrono::milliseconds Timeout=Util::ILockable::DefaultTimeout) const
	Returns whether this `Object` instance is used by other instances. More...

auto	GetUserIDs (const std::chrono::milliseconds Timeout=Util::ILockable::DefaultTimeout) const
	Returns a list of the IDs of the registered users in a thread-safe way. More...

auto	GetUserNamesString (const std::chrono::milliseconds Timeout=Util::ILockable::DefaultTimeout) const
	Builds a string describing which users are registered containing their object names, categories and type names in a thread-safe way. More...

virtual std::string	GetName () const =0
	Returns the name of this `Object` type. More...

Static Public Member Functions
constexpr static auto	Category () noexcept
	Every derived class has to redefine this function. More...

Static Public Member Functions inherited from DynExp::Object
static std::string	CategoryAndNameToStr (const std::string &Category, const std::string &Name)
	Builds a string from an `Object's` category and name to allow the user to identify an `Object's` type. More...

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

Public Attributes inherited from DynExp::RunnableObject
RunnableInstanceOnlyType	RunnableInstanceOnly
	Allow exclusive access to some of `RunnableObject's` private methods to class `RunnableInstance`. More...

Public Attributes inherited from DynExp::Object
LinkedObjectWrapperOnlyType	LinkedObjectWrapperOnly
	Allow exclusive access to some of `Object's` private methods to any LinkedObjectWrapper<T>. More...

Static Public Attributes
static constexpr auto	GetInstrumentDataTimeoutDefault = std::chrono::milliseconds(1000)
	Determines the default timeout for `GetInstrumentData()` to lock the mutex synchronizing the instrument's data InstrumentData. More...

Static Public Attributes inherited from DynExp::RunnableObject
static constexpr auto	ShortTimeoutDefault = std::chrono::milliseconds(50)
	Default timeout e.g. used as a default for calls to InstrumentBase::GetInstrumentData or ModuleBase::GetModuleData. More...

static constexpr auto	TerminateTimeoutDefault = std::chrono::milliseconds(3000)
	Default timeout used as a default for calls to RunnableObject::Terminate. More...

Static Public Attributes inherited from DynExp::Object
static constexpr std::chrono::milliseconds	GetParamsTimeoutDefault = std::chrono::milliseconds(100)
	Default timeout used by Object::GetParams() to lock the mutex of the parameter instance assigned to this `Object` instance. More...

Protected Member Functions
template<typename TaskT , typename... ArgTs>
void	MakeAndEnqueueTask (ArgTs &&...Args) const
	Calls `MakeTask()` to construct a new task and subsequently enqueues the task into the instrument's task queue. Logical const-ness: this is a const member function to allow pointers to `const` `InstrumentBase` inserting tasks into the instrument's task queue. These kind of pointers are e.g. returned by RunnableInstance::GetOwner() which can be called by tasks' TaskBase::RunChild() functions. For `const` `InstrumentBase*`, it is possible to insert tasks into the task queue, but not to change the `InstrumentBase` object itself (e.g. calling Object::Reset()). More...

Protected Member Functions inherited from DynExp::RunnableObject
void	Init ()
	Initializes member variables in case of a reset. More...

std::promise< void >	MakeThreadExitedPromise ()
	Helper function to be used by overridden `RunChild()` functions in derived classes to (re)initialize the ThreadExitedSignal future and to provide the derived class a promise to signal the `RunnableObject` instance that its thread has terminated. More...

void	StoreThread (std::thread &&Thread) noexcept
	Stores a thread constructed by a derived class overriding `RunChild()` in `Thread` taking ownership of the thread. Only call this function within `RunChild()!` More...

bool	IsCallFromRunnableThread () const
	Checks whether `Thread's` id matches the id of the calling thread. This is thread-safe if the function is called by the `RunnableObject` instance's thread since `Terminate()` joins the threads before changing the `Thread` member. It is also thread-safe if the function is called by the thread owning the the `RunnableObject` instance since `Run()` and `Terminate()` can only be called by this thread. Only `Run()` and `Terminate()` (indirectly) modify `Thread`. More...

void	EnsureCallFromRunnableThread () const
	Asserts that the call to this function is performed from the `RunnableObject` instance's thread by calling IsCallFromRunnableThread(). More...

void	SetReasonWhyPaused (std::string Description)
	Sets the reason why this `RunnableObject` instance has been paused. More...

void	SetReasonWhyPaused (const Util::Exception &e)
	Sets the reason why this `RunnableObject` instance has been paused. More...

void	ClearReasonWhyPaused ()
	Removes the reason why this `RunnableObject` instance has been paused (since it is resumed). More...

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

	~INonCopyable ()=default

Protected Member Functions inherited from DynExp::Object
	Object (const std::thread::id OwnerThreadID, ParamsBasePtrType &&Params)
	Constructs an `Object` instance. More...

virtual	~Object ()=0

void	EnsureCallFromOwningThread () const
	Asserts that the call to this function is performed from the thread which constructed this `Object` instance (the thread with the id stored in Object::OwnerThreadID). More...

ParamsTypeSyncPtrType	GetNonConstParams (const std::chrono::milliseconds Timeout=GetParamsTimeoutDefault) const
	Allows derived `Objects` to edit their own parameters - even in const task functions (for instruments) or event functions (for modules). More...

auto	LockUserList (const std::chrono::milliseconds Timeout=Util::ILockable::DefaultTimeout)
	Locks the user list for thread-safe manipulation. More...

void	DeregisterAllUnsafe ()
	Deregisters all users and notifies them that they need to check the states of their used linked objects. More...

auto	GetUseCountUnsafe ()

auto	GetUserNamesStringUnsafe () const

bool	IsUnusedUnsafe ()
	Returns whether this `Object` instance is used by other instances (not thread-safe). More...

Static Protected Member Functions
static auto	GetExceptionUnsafe (const InstrumentDataTypeSyncPtrConstType &InstrumentDataPtr)
	Getter for InstrumentDataBase::InstrumentException. More...

Private Member Functions
void	ResetImpl (dispatch_tag< RunnableObject >) override final
	Refer to DynExp::Object::Reset(). Using tag dispatch mechanism to ensure that `ResetImpl()` of every derived class gets called - starting from DynExp::Object, descending the inheritance hierarchy. More...

virtual void	ResetImpl (dispatch_tag< InstrumentBase >)=0
	Refer to DynExp::Object::Reset(). Using tag dispatch mechanism to ensure that `ResetImpl()` of every derived class gets called - starting from DynExp::Object, descending the inheritance hierarchy. More...

std::exception_ptr	GetExceptionChild ([[maybe_unused]] const std::chrono::milliseconds Timeout) const override final

bool	IsReadyChild () const override final
	Returns wheter this `Object` instance is ready (e.g. it is running or connected to a hardware device) and not blocked (refer to Object::IsBlocked). More...

Private functions for logical const-ness
Logical const-ness: refer to `MakeAndEnqueueTask()`.
InstrumentDataTypeSyncPtrType	GetNonConstInstrumentData (const std::chrono::milliseconds Timeout=GetInstrumentDataTimeoutDefault) const
	Always allows `InstrumentBase` to obtain a non-const pointer to the instrument's data - even in const task functions. More...

Instrument thread only
These functions must be called by instrument thread only.
bool	HandleTask (InstrumentInstance &Instance)
	Executes and removes the next pending task from the instrument's task queue. More...

void	UpdateDataInternal ()
	Inserts an update task (`UpdateTaskBase`) into the instrument's task queue. Override `UpdateAdditionalData()` to adjust behavior. More...

void	OnError ()
	Derived classes can perform critical shutdown actions after an error has occurred. Override `OnErrorChild()` to adjust behavior. More...

Main thread only
These functions must not be called by instrument thread.
void	RunChild () override final
	Refer to `Run()`. More...

void	NotifyChild () override final
	Notify derived classes that some state has changed (e.g. the termination of `Thread` is requested) and that the child's event/task queue should run now. More...

void	TerminateChild (const std::chrono::milliseconds Timeout) override final
	Signals derived classes that terminating the RunnableObject instance's thread is about to be requested. Derived classes might now enqueue respective exit tasks/events into their task/event queues. Refer to `TerminateUnsafe()`. More...

void	OnPrepareExit ()
	This function enables derived classes to enqueue tasks to be executed directly before the final exit task (`ExitTaskBase`). Override `OnPrepareExitChild()` to adjust behavior. More...

Private Attributes
const std::unique_ptr< InstrumentDataType >	InstrumentData
	Instrument data belonging to this `InstrumentBase` instance. More...

std::atomic< bool >	Initialized = false
	Determines whether the init task (`InitTaskBase`) has run. More...

Thread-safe public functions
Methods can be called from any thread.
using	InstrumentDataGetterType = Util::CallableMemberWrapper< InstrumentBase, InstrumentDataTypeSyncPtrType(InstrumentBase::*)(const std::chrono::milliseconds)>
	Invoking an instance of this alias is supposed to call InstrumentBase::GetInstrumentData() of the instance the Util::CallableMemberWrapper has been constructed with. More...

InstrumentDataTypeSyncPtrType	GetInstrumentData (const std::chrono::milliseconds Timeout=GetInstrumentDataTimeoutDefault)
	Locks the mutex of the instrument data class instance InstrumentData assigned to this `InstrumentBase` instance and returns a pointer to the locked InstrumentData. Instrument data should not be locked by having called this function while subsequently calling a derived instrument's method which also makes use of the instrument's data by locking it. If this happens (e.g. in a module thread), the instrument data's mutex is locked recursively. In principle, this does no harm since Util::ISynchronizedPointerLockable supports that. But, it is not considered good practice. More...

InstrumentDataTypeSyncPtrConstType	GetInstrumentData (const std::chrono::milliseconds Timeout=GetInstrumentDataTimeoutDefault) const
	Locks the mutex of the instrument data class instance InstrumentData assigned to this `InstrumentBase` instance and returns a pointer to the locked InstrumentData. Instrument data should not be locked by having called this function while subsequently calling a derived instrument's method which also makes use of the instrument's data by locking it. If this happens (e.g. in a module thread), the instrument data's mutex is locked recursively. In principle, this does no harm since Util::ISynchronizedPointerLockable supports that. But, it is not considered good practice. More...

void	UpdateData () const
	Enqueues an update task (instance of class `UpdateTaskBase`). More...

void	EnqueueArriveAtLatchTask (std::latch &Latch) const
	Enqueues a task which arrives at a latch when executed (instance of class `ArriveAtLatchTask`). More...

bool	IsInitialized () const
	Getter for Initialized. More...

Override
Override by derived classes.
virtual std::chrono::milliseconds	GetTaskQueueDelay () const
	Specifies in which time intervals the instrument's task queue runs to handle pending tasks. More...

virtual void	OnErrorChild () const
	Derived classes can perform critical shutdown actions after an error has occurred. Override `OnErrorChild()` to adjust behavior. More...

virtual void	OnPrepareExitChild () const
	This function enables derived classes to enqueue tasks to be executed directly before the final exit task (`ExitTaskBase`). Override `OnPrepareExitChild()` to adjust behavior. More...

virtual bool	HandleAdditionalTask ()
	Determines whether task handling should continue. More...

virtual bool	UpdateAdditionalData ()
	Determines whether to enqueue update tasks (`UpdateTaskBase`). More...

virtual std::unique_ptr< InitTaskBase >	MakeInitTask () const
	Factory function for an init task (`InitTaskBase`). Override to define the desired initialization task in derived classes only if the respective task really does something and if it has no pure virtual function. More...

virtual std::unique_ptr< ExitTaskBase >	MakeExitTask () const
	Factory function for an exit task (`ExitTaskBase`). Override to define the desired deinitialization task in derived classes only if the respective task really does something and if it has no pure virtual function. More...

virtual std::unique_ptr< UpdateTaskBase >	MakeUpdateTask () const
	Factory function for an update task (`UpdateTaskBase`). Override to define the desired update task in derived classes only if the respective task really does something and if it has no pure virtual function. More...

Detailed Description

Base class for instruments. Instruments comprise virtual devices (meta instruments) and physial devices (instruments). While meta instruments are used by modules (ModuleBase) as an abstraction layer, physical instruments derive from meta instruments and make usually use of one hardware adapter (HardwareAdapterBase) to communicate with the underlying hardware.

Definition at line 450 of file Instrument.h.

Member Typedef Documentation

◆ ConfigType

using DynExp::InstrumentBase::ConfigType = InstrumentConfiguratorBase

Type of the configurator class belonging to this Object type. Declare this alias in every derived class with the respective configurator class accompanying the derived Object.

Definition at line 477 of file Instrument.h.

◆ ExitTaskType

using DynExp::InstrumentBase::ExitTaskType = ExitTaskBase

Defines a task for deinitializing an instrument within an instrument inheritance hierarchy. Each instrument (indirectly) derived from class InstrumentBase must be accompanied by a deinitialization task class derived from ExitTaskBase. Even if the task does not do anything, at least it has to call ExitTaskBase::ExitFuncImpl() of the derived instrument's deinitialization task class.

Definition at line 503 of file Instrument.h.

◆ InitTaskType

using DynExp::InstrumentBase::InitTaskType = InitTaskBase

Defines a task for initializing an instrument within an instrument inheritance hierarchy. Each instrument (indirectly) derived from class InstrumentBase must be accompanied by an initialization task class derived from InitTaskBase. Even if the task does not do anything, at least it has to call InitTaskBase::InitFuncImpl() of the derived instrument's initialization task class.

Definition at line 502 of file Instrument.h.

◆ InstrumentDataGetterType

using DynExp::InstrumentBase::InstrumentDataGetterType = Util::CallableMemberWrapper<InstrumentBase, InstrumentDataTypeSyncPtrType (InstrumentBase::*)(const std::chrono::milliseconds)>

Invoking an instance of this alias is supposed to call InstrumentBase::GetInstrumentData() of the instance the Util::CallableMemberWrapper has been constructed with.

Definition at line 572 of file Instrument.h.

◆ InstrumentDataType

using DynExp::InstrumentBase::InstrumentDataType = InstrumentDataBase

Type of the data class belonging to this InstrumentBase type. Declare this alias in every derived class with the respective data class accompanying the derived InstrumentBase.

Definition at line 483 of file Instrument.h.

◆ InstrumentDataTypeSyncPtrConstType

using DynExp::InstrumentBase::InstrumentDataTypeSyncPtrConstType = Util::SynchronizedPointer<const InstrumentDataType>

Alias for the return type of InstrumentBase::GetInstrumentData() const. Data class instances wrapped into Util::SynchronizedPointer can be accessed in a thread-safe way.

Definition at line 495 of file Instrument.h.

◆ InstrumentDataTypeSyncPtrType

using DynExp::InstrumentBase::InstrumentDataTypeSyncPtrType = Util::SynchronizedPointer<InstrumentDataType>

Alias for the return type of InstrumentBase::GetInstrumentData(). Data class instances wrapped into Util::SynchronizedPointer can be accessed in a thread-safe way.

Definition at line 489 of file Instrument.h.

◆ ParamsType

using DynExp::InstrumentBase::ParamsType = InstrumentParamsBase

Type of the parameter class belonging to this Object type. Declare this alias in every derived class with the respective parameter class accompanying the derived Object.

Definition at line 476 of file Instrument.h.

◆ UpdateTaskType

using DynExp::InstrumentBase::UpdateTaskType = UpdateTaskBase

Defines a task for updating an instrument within an instrument inheritance hierarchy. Each instrument (indirectly) derived from class InstrumentBase must be accompanied by an update task class derived from UpdateTaskBase. Even if the task does not do anything, at least it has to call UpdateTaskBase::UpdateFuncImpl() of the derived instrument's update task class.

Definition at line 504 of file Instrument.h.

Constructor & Destructor Documentation

◆ InstrumentBase()

DynExp::InstrumentBase::InstrumentBase	(	const std::thread::id	OwnerThreadID,
		ParamsBasePtrType &&	Params
	)

Constructs an instrument instance.

Parameters

OwnerThreadID	Thread id of the thread owning the `Object` instance to be constructed.
Params	Parameter class instance to be assigned to the `Object` instance to be constructed.

Exceptions

Util::InvalidArgException	is thrown if `OwnerThreadID` is an invalid thread id or if `Params` is nullptr.
Util::InvalidArgException	is thrown if InstrumentParamsBase::InstrumentData of `Params` is nullptr.

Definition at line 210 of file Instrument.cpp.

◆ ~InstrumentBase()

DynExp::InstrumentBase::~InstrumentBase ( )

pure virtual

Definition at line 218 of file Instrument.cpp.

Member Function Documentation

◆ AsSyncTask()

template<typename DerivedInstrT , typename... TaskFuncArgTs, typename... ArgTs>

ExceptionContainer DynExp::InstrumentBase::AsSyncTask	(	void(DerivedInstrT::*)(TaskFuncArgTs...) const	TaskFunc,
		ArgTs &&...	Args
	)		const

inline

Calls a (derived) instrument's function which inserts a task into the instrument's task queue synchronously. This means that AsSyncTask() blocks until the task has been executed or aborted. This is achieved by passing a callback function to the task which in turn sets a flag after the task execution. The thread calling AsSyncTask() blocks (via std::this_thread::yield()) until this flag is set.

Template Parameters

DerivedInstrT	Instrument type (derived from class `InstrumentBase`).
...TaskFuncArgTs	Types the task inserting function expects as arguments.
...ArgTs	Types of the arguments passed to `AsSyncTask()`.

Parameters

TaskFunc	Member function pointer to (derived) instrument's task-inserting function.
...Args	Arguments to be perfectly forwarded to the task function.

Returns: Return the exception possibly thrown by the task.

Definition at line 649 of file Instrument.h.

◆ Category()

constexpr static auto DynExp::InstrumentBase::Category ( )

inlinestaticconstexprnoexcept

Every derived class has to redefine this function.

Returns: Returns the category of this instrument type.

Definition at line 511 of file Instrument.h.

◆ EnqueueArriveAtLatchTask()

void DynExp::InstrumentBase::EnqueueArriveAtLatchTask ( std::latch & Latch ) const

Enqueues a task which arrives at a latch when executed (instance of class ArriveAtLatchTask).

Parameters

Latch Latch to arrive at.

Definition at line 247 of file Instrument.cpp.

◆ GetCategory()

virtual std::string DynExp::InstrumentBase::GetCategory ( ) const

inlineoverridevirtual

Returns the category of this Object type.

Implements DynExp::Object.

Reimplemented in DynExpInstr::TimeTagger, DynExpInstr::PositionerStage, DynExpInstr::Spectrometer, DynExpInstr::OutputPort, DynExpInstr::LockinAmplifier, DynExpInstr::InputPort, DynExpInstr::gRPCInstrument< Spectrometer, 0, DynExpProto::NetworkSpectrometer::NetworkSpectrometer >, DynExpInstr::gRPCInstrument< DynExp::InstrumentBase, 0, DynExpProto::WidefieldLocalization::WidefieldLocalization >, DynExpInstr::FunctionGenerator, DynExpInstr::DigitalOut, DynExpInstr::DigitalIn, DynExpInstr::DataStreamInstrument, DynExpInstr::Camera, DynExpInstr::AnalogOut, and DynExpInstr::AnalogIn.

Definition at line 522 of file Instrument.h.

◆ GetExceptionChild()

std::exception_ptr DynExp::InstrumentBase::GetExceptionChild ( [[maybe_unused] ] const std::chrono::milliseconds Timeout ) const

finaloverrideprivate

Definition at line 409 of file Instrument.cpp.

◆ GetExceptionUnsafe()

static auto DynExp::InstrumentBase::GetExceptionUnsafe ( const InstrumentDataTypeSyncPtrConstType & InstrumentDataPtr )

inlinestaticprotected

Getter for InstrumentDataBase::InstrumentException.

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

Parameters

InstrumentDataPtr Reference to a pointer to the locked instrument data

Definition at line 612 of file Instrument.h.

◆ GetInstrumentData() [1/2]

InstrumentBase::InstrumentDataTypeSyncPtrType DynExp::InstrumentBase::GetInstrumentData ( const std::chrono::milliseconds Timeout = GetInstrumentDataTimeoutDefault )

Locks the mutex of the instrument data class instance InstrumentData assigned to this InstrumentBase instance and returns a pointer to the locked InstrumentData. Instrument data should not be locked by having called this function while subsequently calling a derived instrument's method which also makes use of the instrument's data by locking it. If this happens (e.g. in a module thread), the instrument data's mutex is locked recursively. In principle, this does no harm since Util::ISynchronizedPointerLockable supports that. But, it is not considered good practice.

Parameters

Timeout Time to wait for locking the mutex of InstrumentData.

Returns: Returns a pointer to InstrumentDataType (non-const) to allow access all of its members.

Definition at line 222 of file Instrument.cpp.

◆ GetInstrumentData() [2/2]

InstrumentBase::InstrumentDataTypeSyncPtrConstType DynExp::InstrumentBase::GetInstrumentData ( const std::chrono::milliseconds Timeout = GetInstrumentDataTimeoutDefault ) const

Locks the mutex of the instrument data class instance InstrumentData assigned to this InstrumentBase instance and returns a pointer to the locked InstrumentData. Instrument data should not be locked by having called this function while subsequently calling a derived instrument's method which also makes use of the instrument's data by locking it. If this happens (e.g. in a module thread), the instrument data's mutex is locked recursively. In principle, this does no harm since Util::ISynchronizedPointerLockable supports that. But, it is not considered good practice.

Parameters

Timeout Time to wait for locking the mutex of InstrumentData.

Returns: Returns a pointer to const InstrumentDataType, since users of this InstrumentBase instance are not allowed to access non-const members of InstrumentDataType. These are only to be accessed by the main thread!

Definition at line 227 of file Instrument.cpp.

◆ GetNonConstInstrumentData()

InstrumentBase::InstrumentDataTypeSyncPtrType DynExp::InstrumentBase::GetNonConstInstrumentData ( const std::chrono::milliseconds Timeout = GetInstrumentDataTimeoutDefault ) const

private

Always allows InstrumentBase to obtain a non-const pointer to the instrument's data - even in const task functions.

Parameters

Timeout Time to wait for locking the mutex of InstrumentData.

Returns: Returns a pointer to InstrumentDataType (non-const) to allow access all of its members.

Definition at line 232 of file Instrument.cpp.

◆ GetTaskQueueDelay()

virtual std::chrono::milliseconds DynExp::InstrumentBase::GetTaskQueueDelay ( ) const

inlinevirtual

Specifies in which time intervals the instrument's task queue runs to handle pending tasks.

Returns: Delay time in between task queue executions. Return std::chrono::milliseconds::max() to make the instrument thread only wake up (to handle tasks and to update data) when a task is enqueued. Return 0 to make the task queue delay as small as as possible.

Reimplemented in DynExpInstr::TimeTagger, DynExpInstr::PositionerStage, DynExpInstr::Spectrometer, DynExpInstr::LockinAmplifier, DynExpInstr::Camera, DynExpInstr::ZI_MFLI, DynExpInstr::SwabianInstrumentsPulseStreamer, DynExpInstr::RS_SMC100A, DynExpInstr::RS_SMB100B, and DynExpInstr::NenionLeakvalveF3.

Definition at line 536 of file Instrument.h.

◆ HandleAdditionalTask()

virtual bool DynExp::InstrumentBase::HandleAdditionalTask ( )

inlineprivatevirtual

Determines whether task handling should continue.

Returns: Returns false if task handling (the instrument) should stop, true otherwise.

Definition at line 726 of file Instrument.h.

◆ HandleTask()

bool DynExp::InstrumentBase::HandleTask ( InstrumentInstance & Instance )

private

Executes and removes the next pending task from the instrument's task queue.

Parameters

Instance Handle to the instrument thread's data

Returns: Returns false if task handling (the instrument) should stop, true otherwise.

Definition at line 254 of file Instrument.cpp.

◆ IsInitialized()

bool DynExp::InstrumentBase::IsInitialized ( ) const

inline

Getter for Initialized.

Returns: Returns true when the instrument is initialized and ready to handle tasks, false othweise.

Definition at line 590 of file Instrument.h.

◆ IsReadyChild()

bool DynExp::InstrumentBase::IsReadyChild ( ) const

finaloverrideprivatevirtual

Returns wheter this Object instance is ready (e.g. it is running or connected to a hardware device) and not blocked (refer to Object::IsBlocked).

Returns: Returns true if this Object instance is ready, false otherwise.

Implements DynExp::Object.

Definition at line 419 of file Instrument.cpp.

◆ MakeAndEnqueueTask()

template<typename TaskT , typename... ArgTs>

void DynExp::InstrumentBase::MakeAndEnqueueTask ( ArgTs &&... Args ) const

inlineprotected

Calls MakeTask() to construct a new task and subsequently enqueues the task into the instrument's task queue. Logical const-ness: this is a const member function to allow pointers to const InstrumentBase inserting tasks into the instrument's task queue. These kind of pointers are e.g. returned by RunnableInstance::GetOwner() which can be called by tasks' TaskBase::RunChild() functions. For const InstrumentBase*, it is possible to insert tasks into the task queue, but not to change the InstrumentBase object itself (e.g. calling Object::Reset()).

Template Parameters

TaskT	Type of a task derived from class `TaskBase`
...ArgTs	Types of the arguments to forward to the task's constructor

Parameters

...Args Arguments to forward to the task's constructor

Definition at line 627 of file Instrument.h.

◆ MakeExitTask()

virtual std::unique_ptr<ExitTaskBase> DynExp::InstrumentBase::MakeExitTask ( ) const

inlineprivatevirtual

Factory function for an exit task (ExitTaskBase). Override to define the desired deinitialization task in derived classes only if the respective task really does something and if it has no pure virtual function.

Returns: Pointer to the task (transferring ownership) or nullptr if no exit task is required. A task can be created with MakeTask().

Reimplemented in DynExpInstr::TimeTagger, DynExpInstr::OutputPort, DynExpInstr::LockinAmplifier, DynExpInstr::InputPort, DynExpInstr::gRPCInstrument< Spectrometer, 0, DynExpProto::NetworkSpectrometer::NetworkSpectrometer >, DynExpInstr::gRPCInstrument< DynExp::InstrumentBase, 0, DynExpProto::WidefieldLocalization::WidefieldLocalization >, DynExpInstr::FunctionGenerator, DynExpInstr::DigitalOut, DynExpInstr::DigitalIn, DynExpInstr::DataStreamInstrument, DynExpInstr::AnalogOut, DynExpInstr::AnalogIn, DynExpInstr::ZI_MFLI, DynExpInstr::WidefieldLocalization, DynExpInstr::SwabianInstrumentsPulseStreamer, DynExpInstr::SmarAct, DynExpInstr::RS_SMC100A, DynExpInstr::RS_SMB100B, DynExpInstr::QutoolsQuTAG, DynExpInstr::PVCam, DynExpInstr::PI_C_862, DynExpInstr::NIDAQDigitalOut, DynExpInstr::NIDAQDigitalIn, DynExpInstr::NIDAQAnalogOut, DynExpInstr::NIDAQAnalogIn, DynExpInstr::NetworkSpectrometer, DynExpInstr::NenionLeakvalveF3, and DynExpInstr::DummyDataStreamInstrument.

Definition at line 751 of file Instrument.h.

◆ MakeInitTask()

virtual std::unique_ptr<InitTaskBase> DynExp::InstrumentBase::MakeInitTask ( ) const

inlineprivatevirtual

Factory function for an init task (InitTaskBase). Override to define the desired initialization task in derived classes only if the respective task really does something and if it has no pure virtual function.

Returns: Pointer to the task (transferring ownership) or nullptr if no init task is required. A task can be created with MakeTask().

Reimplemented in DynExpInstr::TimeTagger, DynExpInstr::OutputPort, DynExpInstr::LockinAmplifier, DynExpInstr::InputPort, DynExpInstr::gRPCInstrument< Spectrometer, 0, DynExpProto::NetworkSpectrometer::NetworkSpectrometer >, DynExpInstr::gRPCInstrument< DynExp::InstrumentBase, 0, DynExpProto::WidefieldLocalization::WidefieldLocalization >, DynExpInstr::FunctionGenerator, DynExpInstr::DigitalOut, DynExpInstr::DigitalIn, DynExpInstr::DataStreamInstrument, DynExpInstr::AnalogOut, DynExpInstr::AnalogIn, DynExpInstr::ZI_MFLI, DynExpInstr::WidefieldLocalization, DynExpInstr::SwabianInstrumentsPulseStreamer, DynExpInstr::SmarAct, DynExpInstr::RS_SMC100A, DynExpInstr::RS_SMB100B, DynExpInstr::QutoolsQuTAG, DynExpInstr::PVCam, DynExpInstr::PI_C_862, DynExpInstr::NIDAQDigitalOut, DynExpInstr::NIDAQDigitalIn, DynExpInstr::NIDAQAnalogOut, DynExpInstr::NIDAQAnalogIn, DynExpInstr::NetworkSpectrometer, DynExpInstr::NenionLeakvalveF3, DynExpInstr::DummyDataStreamInstrument, and DynExpInstr::DummyCamera.

Definition at line 742 of file Instrument.h.

◆ MakeUpdateTask()

virtual std::unique_ptr<UpdateTaskBase> DynExp::InstrumentBase::MakeUpdateTask ( ) const

inlineprivatevirtual

Factory function for an update task (UpdateTaskBase). Override to define the desired update task in derived classes only if the respective task really does something and if it has no pure virtual function.

Returns: Pointer to the task (transferring ownership) or nullptr if no update task is required. A task can be created with MakeTask().

Reimplemented in DynExpInstr::TimeTagger, DynExpInstr::OutputPort, DynExpInstr::LockinAmplifier, DynExpInstr::InputPort, DynExpInstr::gRPCInstrument< Spectrometer, 0, DynExpProto::NetworkSpectrometer::NetworkSpectrometer >, DynExpInstr::gRPCInstrument< DynExp::InstrumentBase, 0, DynExpProto::WidefieldLocalization::WidefieldLocalization >, DynExpInstr::FunctionGenerator, DynExpInstr::DigitalOut, DynExpInstr::DigitalIn, DynExpInstr::DataStreamInstrument, DynExpInstr::AnalogOut, DynExpInstr::AnalogIn, DynExpInstr::ZI_MFLI, DynExpInstr::WidefieldLocalization, DynExpInstr::SwabianInstrumentsPulseStreamer, DynExpInstr::SmarAct, DynExpInstr::RS_SMC100A, DynExpInstr::RS_SMB100B, DynExpInstr::QutoolsQuTAG, DynExpInstr::PVCam, DynExpInstr::PI_C_862, DynExpInstr::NIDAQDigitalOut, DynExpInstr::NIDAQDigitalIn, DynExpInstr::NIDAQAnalogOut, DynExpInstr::NIDAQAnalogIn, DynExpInstr::NetworkSpectrometer, DynExpInstr::NenionLeakvalveF3, DynExpInstr::DummyDataStreamInstrument, and DynExpInstr::DummyCamera.

Definition at line 760 of file Instrument.h.

◆ NotifyChild()

void DynExp::InstrumentBase::NotifyChild ( )

finaloverrideprivatevirtual

Notify derived classes that some state has changed (e.g. the termination of Thread is requested) and that the child's event/task queue should run now.

Reimplemented from DynExp::RunnableObject.

Definition at line 340 of file Instrument.cpp.

◆ OnError()

void DynExp::InstrumentBase::OnError ( )

private

Derived classes can perform critical shutdown actions after an error has occurred. Override OnErrorChild() to adjust behavior.

Definition at line 290 of file Instrument.cpp.

◆ OnErrorChild()

virtual void DynExp::InstrumentBase::OnErrorChild ( ) const

inlineprivatevirtual

Derived classes can perform critical shutdown actions after an error has occurred. Override OnErrorChild() to adjust behavior.

Reimplemented in DynExpInstr::SmarAct, DynExpInstr::PI_C_862, DynExpInstr::NIDAQDigitalOut, DynExpInstr::NIDAQDigitalIn, DynExpInstr::NIDAQAnalogOut, DynExpInstr::NIDAQAnalogIn, and DynExpInstr::NenionLeakvalveF3.

Definition at line 719 of file Instrument.h.

◆ OnPrepareExit()

void DynExp::InstrumentBase::OnPrepareExit ( )

private

This function enables derived classes to enqueue tasks to be executed directly before the final exit task (ExitTaskBase). Override OnPrepareExitChild() to adjust behavior.

Definition at line 385 of file Instrument.cpp.

◆ OnPrepareExitChild()

virtual void DynExp::InstrumentBase::OnPrepareExitChild ( ) const

inlineprivatevirtual

This function enables derived classes to enqueue tasks to be executed directly before the final exit task (ExitTaskBase). Override OnPrepareExitChild() to adjust behavior.

Reimplemented in DynExpInstr::DigitalOut, and DynExpInstr::AnalogOut.

Definition at line 720 of file Instrument.h.

◆ ResetImpl() [1/2]

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

privatepure virtual

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

Implemented in DynExpInstr::gRPCInstrument< DynExp::InstrumentBase, 0, DynExpProto::WidefieldLocalization::WidefieldLocalization >, and DynExpInstr::InterModuleCommunicator.

◆ ResetImpl() [2/2]

void DynExp::InstrumentBase::ResetImpl ( dispatch_tag< RunnableObject > )

finaloverrideprivatevirtual

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

Implements DynExp::RunnableObject.

Definition at line 317 of file Instrument.cpp.

◆ RunChild()

void DynExp::InstrumentBase::RunChild ( )

finaloverrideprivatevirtual

Refer to Run().

Implements DynExp::RunnableObject.

Definition at line 327 of file Instrument.cpp.

◆ TerminateChild()

void DynExp::InstrumentBase::TerminateChild ( const std::chrono::milliseconds Timeout )

finaloverrideprivatevirtual

Signals derived classes that terminating the RunnableObject instance's thread is about to be requested. Derived classes might now enqueue respective exit tasks/events into their task/event queues. Refer to TerminateUnsafe().

Parameters

Timeout Time to wait until the RunnableObject's thread has ended.

Reimplemented from DynExp::RunnableObject.

Definition at line 347 of file Instrument.cpp.

◆ UpdateAdditionalData()

virtual bool DynExp::InstrumentBase::UpdateAdditionalData ( )

inlineprivatevirtual

Determines whether to enqueue update tasks (UpdateTaskBase).

Returns: Returns true if update tasks should be appended to the instrument's task queue periodically after handling all pending tasks, false otherwise.

Definition at line 733 of file Instrument.h.

◆ UpdateData()

void DynExp::InstrumentBase::UpdateData ( ) const

Enqueues an update task (instance of class UpdateTaskBase).

Definition at line 237 of file Instrument.cpp.

◆ UpdateDataInternal()

void DynExp::InstrumentBase::UpdateDataInternal ( )

private

Inserts an update task (UpdateTaskBase) into the instrument's task queue. Override UpdateAdditionalData() to adjust behavior.

Definition at line 280 of file Instrument.cpp.

Member Data Documentation

◆ GetInstrumentDataTimeoutDefault

constexpr auto DynExp::InstrumentBase::GetInstrumentDataTimeoutDefault = std::chrono::milliseconds(1000)

staticconstexpr

Determines the default timeout for GetInstrumentData() to lock the mutex synchronizing the instrument's data InstrumentData.

Definition at line 543 of file Instrument.h.

◆ Initialized

std::atomic<bool> DynExp::InstrumentBase::Initialized = false

private

Determines whether the init task (InitTaskBase) has run.

Definition at line 764 of file Instrument.h.

◆ InstrumentData

const std::unique_ptr<InstrumentDataType> DynExp::InstrumentBase::InstrumentData

private

Instrument data belonging to this InstrumentBase instance.

Definition at line 763 of file Instrument.h.

◆ InstrumentThreadOnly

InstrumenThreadOnlyType DynExp::InstrumentBase::InstrumentThreadOnly

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

Definition at line 524 of file Instrument.h.

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

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Thread-safe public functions

Override

Detailed Description

Member Typedef Documentation

◆ ConfigType

◆ ExitTaskType

◆ InitTaskType

◆ InstrumentDataGetterType

◆ InstrumentDataType

◆ InstrumentDataTypeSyncPtrConstType

◆ InstrumentDataTypeSyncPtrType

◆ ParamsType

◆ UpdateTaskType

Constructor & Destructor Documentation

◆ InstrumentBase()

◆ ~InstrumentBase()

Member Function Documentation

◆ AsSyncTask()

◆ Category()

◆ EnqueueArriveAtLatchTask()

◆ GetCategory()

◆ GetExceptionChild()

◆ GetExceptionUnsafe()

◆ GetInstrumentData() [1/2]

◆ GetInstrumentData() [2/2]

◆ GetNonConstInstrumentData()

◆ GetTaskQueueDelay()

◆ HandleAdditionalTask()

◆ HandleTask()

◆ IsInitialized()

◆ IsReadyChild()

◆ MakeAndEnqueueTask()

◆ MakeExitTask()

◆ MakeInitTask()

◆ MakeUpdateTask()

◆ NotifyChild()

◆ OnError()

◆ OnErrorChild()

◆ OnPrepareExit()

◆ OnPrepareExitChild()

◆ ResetImpl() [1/2]

◆ ResetImpl() [2/2]

◆ RunChild()

◆ TerminateChild()

◆ UpdateAdditionalData()

◆ UpdateData()

◆ UpdateDataInternal()

Member Data Documentation

◆ GetInstrumentDataTimeoutDefault

◆ Initialized

◆ InstrumentData

◆ InstrumentThreadOnly