Base class for register accessors which can be part of a TransferGroup. More...

#include <TransferElement.h>

Inheritance diagram for ChimeraTK::TransferElement:

Collaboration diagram for ChimeraTK::TransferElement:

Public Types
using	SharedPtr = boost::shared_ptr< TransferElement >
	A typedef for more compact syntax. More...

Public Member Functions
	TransferElement (std::string name, AccessModeFlags accessModeFlags, std::string unit=std::string(unitNotSet), std::string description=std::string())
	Creates a transfer element with the specified name. More...

	TransferElement (const TransferElement &other)=delete
	Copying and moving is not allowed. More...

	TransferElement (TransferElement &&other)=delete

TransferElement &	operator= (const TransferElement &other)=delete

TransferElement &	operator= (TransferElement &&other)=delete

virtual	~TransferElement ()=default
	Abstract base classes need a virtual destructor. More...

const std::string &	getName () const
	Returns the name that identifies the process variable. More...

const std::string &	getUnit () const
	Returns the engineering unit. More...

const std::string &	getDescription () const
	Returns the description of this variable/register. More...

virtual const std::type_info &	getValueType () const =0
	Returns the `std::type_info` for the value type of this transfer element. More...

AccessModeFlags	getAccessModeFlags () const
	Return the AccessModeFlags for this TransferElement. More...

void	setDataValidity (DataValidity validity=DataValidity::ok)
	Set the current DataValidity for this TransferElement. More...

DataValidity	dataValidity () const
	Return current validity of the data. More...

void	read ()
	Read the data from the device. More...

bool	readNonBlocking ()
	Read the next value, if available in the input buffer. More...

bool	readLatest ()
	Read the latest value, discarding any other update since the last read if present. More...

bool	write (ChimeraTK::VersionNumber versionNumber={})
	Write the data to device. More...

bool	writeDestructively (ChimeraTK::VersionNumber versionNumber={})
	Just like write(), but allows the implementation to destroy the content of the user buffer in the process. More...

ChimeraTK::VersionNumber	getVersionNumber () const
	Returns the version number that is associated with the last transfer (i.e. More...

virtual bool	isReadOnly () const =0
	Check if transfer element is read only, i.e. More...

virtual bool	isReadable () const =0
	Check if transfer element is readable. More...

virtual bool	isWriteable () const =0
	Check if transfer element is writeable. More...

void	setActiveException (std::exception_ptr &setThisException)
	Set an active exception. More...

virtual void	setExceptionBackend (boost::shared_ptr< DeviceBackend > exceptionBackend)
	Set the backend to which the exception has to be reported. More...

boost::shared_ptr< DeviceBackend >	getExceptionBackend ()
	Return the exception backend. More...

cppext::future_queue< void >	getReadQueue ()
	Function to get a copy of the read queue. More...

void	readTransfer ()
	Read the data from the device but do not fill it into the user buffer of this TransferElement. More...

bool	readTransferNonBlocking ()
	Read the data from the device but do not fill it into the user buffer of this TransferElement. More...

void	preRead (TransferType type)
	Perform any pre-read tasks if necessary. More...

void	postRead (TransferType type, bool updateDataBuffer)
	Transfer the data from the device receive buffer into the user buffer, while converting the data into the user data format if needed. More...

void	preWrite (TransferType type, ChimeraTK::VersionNumber versionNumber)
	Transfer the data from the user buffer into the device send buffer, while converting the data from then user data format if needed. More...

void	postWrite (TransferType type, VersionNumber versionNumber)
	Perform any post-write clean-ups if necessary. More...

bool	writeTransfer (ChimeraTK::VersionNumber versionNumber)
	Write the data to the device. More...

bool	writeTransferDestructively (ChimeraTK::VersionNumber versionNumber)
	Write the data to the device. More...

virtual bool	mayReplaceOther (const boost::shared_ptr< TransferElement const > &other) const
	Check whether the TransferElement can be used in places where the TransferElement "other" is currently used, e.g. More...

virtual std::vector< boost::shared_ptr< TransferElement > >	getHardwareAccessingElements ()=0
	Obtain the underlying TransferElements with actual hardware access. More...

virtual std::list< boost::shared_ptr< TransferElement > >	getInternalElements ()=0
	Obtain the full list of TransferElements internally used by this TransferElement. More...

virtual boost::shared_ptr< TransferElement >	getHighLevelImplElement ()
	Obtain the highest level implementation TransferElement. More...

virtual void	replaceTransferElement ([[maybe_unused]] boost::shared_ptr< TransferElement > newElement)
	Search for all underlying TransferElements which are considered identical (see sameRegister()) with the given TransferElement. More...

virtual boost::shared_ptr< TransferElement >	makeCopyRegisterDecorator ()=0
	Create a CopyRegisterDecorator of the right type decorating this TransferElement. More...

virtual void	setPersistentDataStorage (boost::shared_ptr< ChimeraTK::PersistentDataStorage >)
	Associate a persistent data storage object to be updated on each write operation of this ProcessArray. More...

TransferElementID	getId () const
	Obtain unique ID for this TransferElement, see TransferElementID for details. More...

virtual void	interrupt ()
	Return from a blocking read immediately and throw boost::thread_interrupted. More...

template<typename QUEUE_TYPE >
void	interrupt_impl (QUEUE_TYPE &dataTransportQueue)
	Implementation of interrupt() More...

bool	isReadTransactionInProgress () const
	Check whether a read transaction is in progress, i.e. More...

bool	isWriteTransactionInProgress () const
	Check whether a write transaction is in progress, i.e. More...

Static Public Attributes
static constexpr char	unitNotSet [] = "n./a."
	Constant string to be used as a unit when the unit is not provided or known. More...

Protected Member Functions
virtual void	doReadTransferSynchronously ()=0
	Implementation version of readTransfer() for synchronous reads. More...

virtual void	doPreRead (TransferType)
	Backend specific implementation of preRead(). More...

virtual void	doPostRead (TransferType, bool)
	Backend specific implementation of postRead(). More...

virtual void	doPreWrite (TransferType, VersionNumber)
	Backend specific implementation of preWrite(). More...

virtual void	doPostWrite (TransferType, VersionNumber)
	Backend specific implementation of postWrite(). More...

virtual bool	doWriteTransfer (ChimeraTK::VersionNumber versionNumber)=0
	Implementation version of writeTransfer(). More...

virtual bool	doWriteTransferDestructively (ChimeraTK::VersionNumber versionNumber)
	Implementation version of writeTransferDestructively(). More...

void	makeUniqueId ()
	Allow generating a unique ID from derived classes. More...

Protected Attributes
boost::shared_ptr< DeviceBackend >	_exceptionBackend
	The backend to which the runtime_errors are reported via DeviceBackend::setException(). More...

std::string	_name
	Identifier uniquely identifying the TransferElement. More...

std::string	_unit
	Engineering unit. More...

std::string	_description
	Description of this variable/register. More...

TransferElementID	_id
	The ID of this TransferElement. More...

bool	_isInTransferGroup {false}
	Flag whether this TransferElement has been added to a TransferGroup or not. More...

bool	_isInReadAnyGroup {false}
	Flag whether this TransferElement has been added to a ReadAnyGroup or not. More...

AccessModeFlags	_accessModeFlags
	The access mode flags for this transfer element. More...

cppext::future_queue< void >	_readQueue
	The queue for asynchronous read transfers. More...

VersionNumber	_versionNumber {nullptr}
	The version number of the last successful transfer. More...

DataValidity	_dataValidity {DataValidity::ok}
	The validity of the data in the application buffer. More...

std::exception_ptr	_activeException {nullptr}
	Exception to be rethrown in postXXX() in case hasSeenException == true Can be set via setActiveException(). More...

Friends
class	TransferGroup

class	ReadAnyGroup

Detailed Description

Base class for register accessors which can be part of a TransferGroup.

Definition at line 67 of file TransferElement.h.

Member Typedef Documentation

◆ SharedPtr

using ChimeraTK::TransferElement::SharedPtr = boost::shared_ptr<TransferElement>

A typedef for more compact syntax.

Definition at line 85 of file TransferElement.h.

Constructor & Destructor Documentation

◆ TransferElement() [1/3]

ChimeraTK::TransferElement::TransferElement	(	std::string	name,
		AccessModeFlags	accessModeFlags,
		std::string	unit = `std::string(unitNotSet)`,
		std::string	description = `std::string()`
	)

inline

Creates a transfer element with the specified name.

Definition at line 70 of file TransferElement.h.

◆ TransferElement() [2/3]

ChimeraTK::TransferElement::TransferElement ( const TransferElement & other )

delete

Copying and moving is not allowed.

◆ TransferElement() [3/3]

ChimeraTK::TransferElement::TransferElement ( TransferElement && other )

delete

◆ ~TransferElement()

virtual ChimeraTK::TransferElement::~TransferElement ( )

virtualdefault

Abstract base classes need a virtual destructor.

Member Function Documentation

◆ dataValidity()

DataValidity ChimeraTK::TransferElement::dataValidity ( ) const

inline

Return current validity of the data.

Will always return DataValidity::ok if the backend does not support it

Definition at line 111 of file TransferElement.h.

◆ doPostRead()

virtual void ChimeraTK::TransferElement::doPostRead	(	TransferType	,
		bool
	)

inlineprotectedvirtual

Backend specific implementation of postRead().

postRead() will call this function, but it will make sure that it gets called only once per transfer.

No actual communication may be done. Hence, no runtime_error exception may be thrown by this function. Also it must be acceptable to call this function while the device is closed or not functional (see isFunctional()) and no exception is thrown.

Notes for backend implementations:

If the flag updateDataBuffer is false, the data buffer must stay unaltered. Full implementations (backends) must also leave the meta data (version number and data validity) unchanged. Decorators are allowed to change the meta data (for instance set the DataValidity::faulty).

Reimplemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

Definition at line 503 of file TransferElement.h.

Here is the caller graph for this function:

◆ doPostWrite()

virtual void ChimeraTK::TransferElement::doPostWrite	(	TransferType	,
		VersionNumber
	)

inlineprotectedvirtual

Backend specific implementation of postWrite().

postWrite() will call this function, but it will make sure that it gets called only once per transfer.

No actual communication may be done. Hence, no runtime_error exception may be thrown by this function. Also it must be acceptable to call this function while the device is closed or not functional (see isFunctional()) and no exception is thrown.

Reimplemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

Definition at line 599 of file TransferElement.h.

Here is the caller graph for this function:

◆ doPreRead()

virtual void ChimeraTK::TransferElement::doPreRead ( TransferType )

inlineprotectedvirtual

Backend specific implementation of preRead().

preRead() will call this function, but it will make sure that it gets called only once per transfer.

No actual communication may be done. Hence, no runtime_error exception may be thrown by this function. Also it must be acceptable to call this function while the device is closed or not functional (see isFunctional()) and no exception is thrown.

Definition at line 448 of file TransferElement.h.

Here is the caller graph for this function:

◆ doPreWrite()

virtual void ChimeraTK::TransferElement::doPreWrite	(	TransferType	,
		VersionNumber
	)

inlineprotectedvirtual

Backend specific implementation of preWrite().

preWrite() will call this function, but it will make sure that it gets called only once per transfer.

No actual communication may be done. Hence, no runtime_error exception may be thrown by this function. Also it must be acceptable to call this function while the device is closed or not functional (see isFunctional()) and no exception is thrown.

Reimplemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

Definition at line 549 of file TransferElement.h.

Here is the caller graph for this function:

◆ doReadTransferSynchronously()

virtual void ChimeraTK::TransferElement::doReadTransferSynchronously ( )

protectedpure virtual

Implementation version of readTransfer() for synchronous reads.

This function must be implemented by the backend. For the functional description read the documentation of readTransfer().

Implementation notes:

This function must return within ~1 second after both boost::thread::interrupt() (on the thread calling this function) and TransferElement::interrupt() have been called (reliable termination requires both calls; implementation needs to react to one of the call only).
Decorators must delegate the call to readTransfer() of the decorated target.
Delegations within the same object should go to the "do" version, e.g. to BaseClass::doReadTransferSynchronously()

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

Here is the caller graph for this function:

◆ doWriteTransfer()

virtual bool ChimeraTK::TransferElement::doWriteTransfer ( ChimeraTK::VersionNumber versionNumber )

protectedpure virtual

Implementation version of writeTransfer().

This function must be implemented by the backend. For the functional description read the documentation of writeTransfer().

Implementation notes:

Decorators must delegate the call to writeTransfer() of the decorated target.

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

Here is the caller graph for this function:

◆ doWriteTransferDestructively()

virtual bool ChimeraTK::TransferElement::doWriteTransferDestructively ( ChimeraTK::VersionNumber versionNumber )

inlineprotectedvirtual

Implementation version of writeTransferDestructively().

This function must be implemented by the backend. For the functional description read the documentation of writeTransfer().

Implementation notes:

Decorators must delegate the call to writeTransfer() of the decorated target.
Delegations within the same object should go to the "do" version, e.g. to this->doWriteTransfer()
The implementation may destroy the content of the user buffer in the process. This is an optional optimisation, hence there is a default implementation which just calls the normal doWriteTransfer().

Definition at line 649 of file TransferElement.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getAccessModeFlags()

AccessModeFlags ChimeraTK::TransferElement::getAccessModeFlags ( ) const

inline

Return the AccessModeFlags for this TransferElement.

Definition at line 103 of file TransferElement.h.

◆ getDescription()

const std::string& ChimeraTK::TransferElement::getDescription ( ) const

inline

Returns the description of this variable/register.

Definition at line 95 of file TransferElement.h.

◆ getExceptionBackend()

boost::shared_ptr<DeviceBackend> ChimeraTK::TransferElement::getExceptionBackend ( )

inline

Return the exception backend.

Needed by decorators to set their _exceptionBackend to the target's.

Definition at line 301 of file TransferElement.h.

◆ getHardwareAccessingElements()

virtual std::vector<boost::shared_ptr<TransferElement> > ChimeraTK::TransferElement::getHardwareAccessingElements ( )

pure virtual

Obtain the underlying TransferElements with actual hardware access.

If this transfer element is directly reading from / writing to the hardware, it will return a list just containing a shared pointer of itself.

Note: Avoid using this in application code, since it will break the abstraction!

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

◆ getHighLevelImplElement()

virtual boost::shared_ptr<TransferElement> ChimeraTK::TransferElement::getHighLevelImplElement ( )

inlinevirtual

Obtain the highest level implementation TransferElement.

For TransferElements which are itself an implementation this will directly return a shared pointer to this. If this TransferElement is a user frontend, the pointer to the internal implementation is returned.

Note: Avoid using this in application code, since it will break the abstraction!

Definition at line 722 of file TransferElement.h.

◆ getId()

TransferElementID ChimeraTK::TransferElement::getId ( ) const

inline

Obtain unique ID for this TransferElement, see TransferElementID for details.

Definition at line 762 of file TransferElement.h.

◆ getInternalElements()

virtual std::list<boost::shared_ptr<TransferElement> > ChimeraTK::TransferElement::getInternalElements ( )

pure virtual

Obtain the full list of TransferElements internally used by this TransferElement.

The function is recursive, i.e. elements used by the elements returned by this function are also added to the list. It is guaranteed that the directly used elements are first in the list and the result from recursion is appended to the list.

Example: A decorator would return a list with its target TransferElement followed by the result of getInternalElements() called on its target TransferElement.

If this TransferElement is not using any other element, it should return an empty vector. Thus those elements which return a list just containing themselves in getHardwareAccessingElements() will return an empty list here in getInternalElements().

Note: Avoid using this in application code, since it will break the abstraction!

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

◆ getName()

const std::string& ChimeraTK::TransferElement::getName ( ) const

inline

Returns the name that identifies the process variable.

Definition at line 88 of file TransferElement.h.

Here is the caller graph for this function:

◆ getReadQueue()

cppext::future_queue<void> ChimeraTK::TransferElement::getReadQueue ( )

inline

Function to get a copy of the read queue.

This functions should only be used by decorators to initialise their TransferElement::_readQueue() member.

Definition at line 306 of file TransferElement.h.

◆ getUnit()

const std::string& ChimeraTK::TransferElement::getUnit ( ) const

inline

Returns the engineering unit.

If none was specified, it will default to "n./a."

Definition at line 92 of file TransferElement.h.

◆ getValueType()

virtual const std::type_info& ChimeraTK::TransferElement::getValueType ( ) const

pure virtual

Returns the std::type_info for the value type of this transfer element.

This can be used to determine the type at runtime.

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

◆ getVersionNumber()

ChimeraTK::VersionNumber ChimeraTK::TransferElement::getVersionNumber ( ) const

inline

Returns the version number that is associated with the last transfer (i.e.

last read or write). See ChimeraTK::VersionNumber for details. The VersionNumber object also allows to determine the time stamp.

Implementation notes:

Reading accessors have to update the TransferElement _versionNumber variable in their doPostRead function. For TransferElements with AccessMode::wait_for_new_data it has to be created already when the data is received. It must be stored together with the payload data and only written to the application buffer (which _versionNumber is a part of) in postWrite. Accessors which rely on other accessors to obtain their data update the value from their target after a successful transfer.

Definition at line 259 of file TransferElement.h.

Here is the caller graph for this function:

◆ interrupt()

virtual void ChimeraTK::TransferElement::interrupt ( )

inlinevirtual

Return from a blocking read immediately and throw boost::thread_interrupted.

This function can be used to shutdown a thread waiting on data to arrive, which might never happen because the sending part of the application is already shut down, or there is no new data at the moment.

Note that this function does not stop the sending thread. It just places a boost::thread_interrupted exception on the _TransferElement::_readQueue, so a waiting read() has something to receive and returns. If regular data is put into the queue just before the exception, this is received first. Hence it is not guaranteed that the read call that is supposed to be interrupted will actually throw an exception. But it is guaranteed that it returns immediately. Also it is guaranteed that eventually the boost::thread_interrupted exception will be received, unless more values are written to the queue and the exception is overwritten.

See Technical specification: TransferElement B.8.6

Implementation notice: This default implementation is always doing nothing. Each TransferElement implementation that supports AccessMode::wait_for_new_data (or may need to interrupt synchronous read calls) has to override it like this (unless the TransferElement has special requirements): void interrupt() override { this->interrupt_impl(this->_myDataTransportQueue); }

Definition at line 783 of file TransferElement.h.

◆ interrupt_impl()

template<typename QUEUE_TYPE >

void ChimeraTK::TransferElement::interrupt_impl ( QUEUE_TYPE & dataTransportQueue )

inline

Implementation of interrupt()

This function shall be called by backends in their interrupt() implementation as stated in its implementation note.

Definition at line 792 of file TransferElement.h.

◆ isReadable()

virtual bool ChimeraTK::TransferElement::isReadable ( ) const

pure virtual

Check if transfer element is readable.

It throws an exception if you try to read and isReadable() is not true.

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

◆ isReadOnly()

virtual bool ChimeraTK::TransferElement::isReadOnly ( ) const

pure virtual

Check if transfer element is read only, i.e.

it is readable but not writeable.

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

◆ isReadTransactionInProgress()

bool ChimeraTK::TransferElement::isReadTransactionInProgress ( ) const

inline

Check whether a read transaction is in progress, i.e.

preRead() has been called but not yet postRead().

Definition at line 797 of file TransferElement.h.

◆ isWriteable()

virtual bool ChimeraTK::TransferElement::isWriteable ( ) const

pure virtual

Check if transfer element is writeable.

It throws an exception if you try to write and isWriteable() is not true.

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

◆ isWriteTransactionInProgress()

bool ChimeraTK::TransferElement::isWriteTransactionInProgress ( ) const

inline

Check whether a write transaction is in progress, i.e.

preWrite() has been called but not yet postWrite().

Definition at line 800 of file TransferElement.h.

◆ makeCopyRegisterDecorator()

virtual boost::shared_ptr<TransferElement> ChimeraTK::TransferElement::makeCopyRegisterDecorator ( )

pure virtual

Create a CopyRegisterDecorator of the right type decorating this TransferElement.

This is used by TransferElementAbstractor::replaceTransferElement() to decouple two accessors which are replaced on the abstractor level.

Implemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

◆ makeUniqueId()

void ChimeraTK::TransferElement::makeUniqueId ( )

inlineprotected

Allow generating a unique ID from derived classes.

Definition at line 816 of file TransferElement.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mayReplaceOther()

virtual bool ChimeraTK::TransferElement::mayReplaceOther ( const boost::shared_ptr< TransferElement const > & other ) const

inlinevirtual

Check whether the TransferElement can be used in places where the TransferElement "other" is currently used, e.g.

to merge the two transfers. This function must be used in replaceTransferElement() by implementations which use other TransferElements, to determine if a used TransferElement shall be replaced with the TransferElement "other".

The purpose of this function is not to determine if at any point in the hierarchy an replacement could be done. This function only works on a single level. It is not used by the TransferGroup to determine replaceTransferElement() whether shall be used (it is always called). Instead this function can be used by decorators etc. inside their implementation of replaceTransferElement() to determine if they might swap their implementation(s).

Note for decorators and similar implementations: This function must not be decorated. It should only return true if this should actually be replaced with other in the call to replaceTransferElement() one level up in the hierarchy. If the replacement should be done further down in the hierarchy, simply return false. It should only return if other is fully identical to this (i.e. behaves identical in all situations but might be another instance).

Reimplemented in ChimeraTK::NumericAddressedLowLevelTransferElement.

Definition at line 677 of file TransferElement.h.

◆ operator=() [1/2]

TransferElement& ChimeraTK::TransferElement::operator= ( const TransferElement & other )

delete

◆ operator=() [2/2]

TransferElement& ChimeraTK::TransferElement::operator= ( TransferElement && other )

delete

◆ postRead()

void ChimeraTK::TransferElement::postRead	(	TransferType	type,
		bool	updateDataBuffer
	)

inline

Transfer the data from the device receive buffer into the user buffer, while converting the data into the user data format if needed.

Called by read() etc. Also the TransferGroup will call this function after a read was executed directly on the underlying accessor. This function must be implemented to extract the read data from the underlying accessor and expose it to the user.

Definition at line 473 of file TransferElement.h.

Here is the call graph for this function:

◆ postWrite()

void ChimeraTK::TransferElement::postWrite	(	TransferType	type,
		VersionNumber	versionNumber
	)

inline

Perform any post-write clean-ups if necessary.

If during preWrite() e.g. the user data buffer was swapped away, it must be swapped back in this function so the just sent data is available again to the calling program.

Called by write(). Also the TransferGroup will call this function after a write was executed directly on the underlying accessor.

Definition at line 573 of file TransferElement.h.

Here is the call graph for this function:

◆ preRead()

void ChimeraTK::TransferElement::preRead ( TransferType type )

inline

Perform any pre-read tasks if necessary.

Called by read() etc. Also the TransferGroup will call this function before a read is executed directly on the underlying accessor.

Definition at line 432 of file TransferElement.h.

Here is the call graph for this function:

◆ preWrite()

void ChimeraTK::TransferElement::preWrite	(	TransferType	type,
		ChimeraTK::VersionNumber	versionNumber
	)

inline

Transfer the data from the user buffer into the device send buffer, while converting the data from then user data format if needed.

Called by write(). Also the TransferGroup will call this function before a write will be executed directly on the underlying accessor. This function implemented be used to transfer the data to be written into the underlying accessor.

Definition at line 530 of file TransferElement.h.

Here is the call graph for this function:

◆ read()

void ChimeraTK::TransferElement::read ( )

inline

Read the data from the device.

If AccessMode::wait_for_new_data was set, this function will block until new data has arrived. Otherwise it still might block for a short time until the data transfer was complete.

Definition at line 116 of file TransferElement.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readLatest()

bool ChimeraTK::TransferElement::readLatest ( )

inline

Read the latest value, discarding any other update since the last read if present.

Otherwise this function is identical to readNonBlocking(), i.e. it will never wait for new values and it will return whether a new value was available if AccessMode::wait_for_new_data is set.

Definition at line 185 of file TransferElement.h.

Here is the call graph for this function:

◆ readNonBlocking()

bool ChimeraTK::TransferElement::readNonBlocking ( )

inline

Read the next value, if available in the input buffer.

If AccessMode::wait_for_new_data was set, this function returns immediately and the return value indicated if a new value was available (true) or not (false).

If AccessMode::wait_for_new_data was not set, this function is identical to read(), which will still return quickly. Depending on the actual transfer implementation, the backend might need to transfer data to obtain the current value before returning. Also this function is not guaranteed to be lock free. The return value will be always true in this mode.

Definition at line 146 of file TransferElement.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readTransfer()

void ChimeraTK::TransferElement::readTransfer ( )

inline

Read the data from the device but do not fill it into the user buffer of this TransferElement.

This function must be called after preRead() and before postRead(). If the accessor has the AccessMode::wait_for_new_data flag, the function will block until new data has been pushed by the sender.

This function internally calls doReadTransferSynchronously(), which is implemented by the backend, or waits for data on the _readQueue, depending whether AccessMode::wait_for_new_data is set. runtime_error exceptions thrown in the transfer are caught and rethrown in postRead().

Definition at line 354 of file TransferElement.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ readTransferNonBlocking()

bool ChimeraTK::TransferElement::readTransferNonBlocking ( )

inline

Read the data from the device but do not fill it into the user buffer of this TransferElement.

This function must be called after preRead() and before postRead(). Even if the accessor has the AccessMode::wait_for_new_data flag, this function will not block if no new data is available. For the meaning of the return value, see readNonBlocking().

For TransferElements with AccessMode::wait_for_new_data this function checks whether there is new data on the _readQueue. Without AccessMode::wait_for_new_data it calls doReadTransferSynchronously, which is implemented by the backend. runtime_error exceptions thrown in the transfer are caught and rethrown in postRead().

Definition at line 402 of file TransferElement.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ replaceTransferElement()

virtual void ChimeraTK::TransferElement::replaceTransferElement ( [[maybe_unused] ] boost::shared_ptr< TransferElement > newElement )

inlinevirtual

Search for all underlying TransferElements which are considered identical (see sameRegister()) with the given TransferElement.

These TransferElements are then replaced with the new element. If no underlying element matches the new element, this function has no effect.

Definition at line 732 of file TransferElement.h.

◆ setActiveException()

void ChimeraTK::TransferElement::setActiveException ( std::exception_ptr & setThisException )

inline

Set an active exception.

This function is called by all decorator-like TransferElements to propagate exceptions to their target. The argument is passed by reference. After returning from this function, it is {nullptr}. This function must not be called with nullptr (see spec FIXME).

Definition at line 278 of file TransferElement.h.

◆ setDataValidity()

void ChimeraTK::TransferElement::setDataValidity ( DataValidity validity = DataValidity::ok )

inline

Set the current DataValidity for this TransferElement.

Will do nothing if the backend does not support it

Definition at line 107 of file TransferElement.h.

◆ setExceptionBackend()

virtual void ChimeraTK::TransferElement::setExceptionBackend ( boost::shared_ptr< DeviceBackend > exceptionBackend )

inlinevirtual

Set the backend to which the exception has to be reported.

Each backend has to do this when creating TransferElements. However, not all TransferElements will have it set, for instance ProcessArrays in the ControlSystemAdapter and Application core,# which don't have backends at all. This function is only to be called inside of DeviceBackend::getRegisterAccessor()!

It is virtual because some accessor implementations like NumericAddressedBackendRegisterAccessor have an inner layer (LowLevelTransferElement), and all layers need to know the exception backend. Hence the functions needs to be overridden in this case.

Definition at line 295 of file TransferElement.h.

Here is the caller graph for this function:

◆ setPersistentDataStorage()

virtual void ChimeraTK::TransferElement::setPersistentDataStorage ( boost::shared_ptr< ChimeraTK::PersistentDataStorage > )

inlinevirtual

Associate a persistent data storage object to be updated on each write operation of this ProcessArray.

If no persistent data storage as associated previously, the value from the persistent storage is read and send to the receiver.

Note: A call to this function will be ignored, if the TransferElement does not support persistent data storage (e.g. read-only variables or device registers)

Todo:: TODO does this make sense?

Definition at line 756 of file TransferElement.h.

◆ write()

bool ChimeraTK::TransferElement::write ( ChimeraTK::VersionNumber versionNumber = {} )

inline

Write the data to device.

The return value is true, old data was lost on the write transfer (e.g. due to an buffer overflow). In case of an unbuffered write transfer, the return value will always be false.

Definition at line 204 of file TransferElement.h.

◆ writeDestructively()

bool ChimeraTK::TransferElement::writeDestructively ( ChimeraTK::VersionNumber versionNumber = {} )

inline

Just like write(), but allows the implementation to destroy the content of the user buffer in the process.

This is an optional optimisation, hence there is a default implementation which just calls the normal doWriteTransfer(). In any case, the application must expect the user buffer of the TransferElement to contain undefined data after calling this function.

Definition at line 226 of file TransferElement.h.

◆ writeTransfer()

bool ChimeraTK::TransferElement::writeTransfer ( ChimeraTK::VersionNumber versionNumber )

inline

Write the data to the device.

This function must be called after preWrite() and before postWrite(). If the return value is true, old data was lost on the write transfer (e.g. due to an buffer overflow). In case of an unbuffered write transfer, the return value will always be false.

This function internally calls doWriteTransfer(), which is implemented by the backend. runtime_error exceptions thrown in doWriteTransfer() are caught and rethrown in postWrite().

Definition at line 610 of file TransferElement.h.

Here is the call graph for this function:

◆ writeTransferDestructively()

bool ChimeraTK::TransferElement::writeTransferDestructively ( ChimeraTK::VersionNumber versionNumber )

inline

Write the data to the device.

The implementation is allowed to destroy the content of the user buffer in the process. This is an optional optimisation, hence the behaviour might be identical to writeTransfer().

This function must be called after preWrite() and before postWrite(). If the return value is true, old data was lost on the write transfer (e.g. due to an buffer overflow). In case of an unbuffered write transfer, the return value will always be false.

This function internally calls doWriteTransfer(), which is implemented by the backend. runtime_error exceptions thrown in doWriteTransfer() are caught and rethrown in postWrite().

Definition at line 634 of file TransferElement.h.

Here is the call graph for this function:

Friends And Related Function Documentation

◆ ReadAnyGroup

friend class ReadAnyGroup

friend

Definition at line 829 of file TransferElement.h.

◆ TransferGroup

friend class TransferGroup

friend

Definition at line 828 of file TransferElement.h.

Member Data Documentation

◆ _accessModeFlags

AccessModeFlags ChimeraTK::TransferElement::_accessModeFlags

protected

The access mode flags for this transfer element.

Definition at line 826 of file TransferElement.h.

◆ _activeException

std::exception_ptr ChimeraTK::TransferElement::_activeException {nullptr}

protected

Exception to be rethrown in postXXX() in case hasSeenException == true Can be set via setActiveException().

Definition at line 859 of file TransferElement.h.

◆ _dataValidity

DataValidity ChimeraTK::TransferElement::_dataValidity {DataValidity::ok}

protected

The validity of the data in the application buffer.

Part of the application buffer (see TransferElement specification A.5)

Definition at line 855 of file TransferElement.h.

◆ _description

std::string ChimeraTK::TransferElement::_description

protected

Description of this variable/register.

Definition at line 810 of file TransferElement.h.

◆ _exceptionBackend

boost::shared_ptr<DeviceBackend> ChimeraTK::TransferElement::_exceptionBackend

protected

The backend to which the runtime_errors are reported via DeviceBackend::setException().

Creating backends set it in DeviceBackend::getRegisterAccessor(). Decorators have to set it in the constructor from their target.

Definition at line 313 of file TransferElement.h.

◆ _id

TransferElementID ChimeraTK::TransferElement::_id

protected

The ID of this TransferElement.

Definition at line 813 of file TransferElement.h.

◆ _isInReadAnyGroup

bool ChimeraTK::TransferElement::_isInReadAnyGroup {false}

protected

Flag whether this TransferElement has been added to a ReadAnyGroup or not.

Definition at line 823 of file TransferElement.h.

◆ _isInTransferGroup

bool ChimeraTK::TransferElement::_isInTransferGroup {false}

protected

Flag whether this TransferElement has been added to a TransferGroup or not.

Definition at line 820 of file TransferElement.h.

◆ _name

std::string ChimeraTK::TransferElement::_name

protected

Identifier uniquely identifying the TransferElement.

Definition at line 804 of file TransferElement.h.

◆ _readQueue

cppext::future_queue<void> ChimeraTK::TransferElement::_readQueue

protected

The queue for asynchronous read transfers.

This is the void queue which is a continuation of the actual data transport queue, which is implementation dependent. With _readQueue the exception propagation and waiting for new data is implemented in TransferElement.

Definition at line 847 of file TransferElement.h.

◆ _unit

std::string ChimeraTK::TransferElement::_unit

protected

Engineering unit.

Defaults to "n./a.", if none was specified

Definition at line 807 of file TransferElement.h.

◆ _versionNumber

VersionNumber ChimeraTK::TransferElement::_versionNumber {nullptr}

protected

The version number of the last successful transfer.

Part of the application buffer (see TransferElement specification A.5)

Definition at line 851 of file TransferElement.h.

◆ unitNotSet

constexpr char ChimeraTK::TransferElement::unitNotSet[] = "n./a."

staticconstexpr

Constant string to be used as a unit when the unit is not provided or known.

Definition at line 742 of file TransferElement.h.

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

/scratch/dragon/sources/ChimeraTK-DeviceAccess/include/TransferElement.h

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ SharedPtr

Constructor & Destructor Documentation

◆ TransferElement() [1/3]

◆ TransferElement() [2/3]

◆ TransferElement() [3/3]

◆ ~TransferElement()

Member Function Documentation

◆ dataValidity()

◆ doPostRead()

◆ doPostWrite()

◆ doPreRead()

◆ doPreWrite()

◆ doReadTransferSynchronously()

◆ doWriteTransfer()

◆ doWriteTransferDestructively()

◆ getAccessModeFlags()

◆ getDescription()

◆ getExceptionBackend()

◆ getHardwareAccessingElements()

◆ getHighLevelImplElement()

◆ getId()

◆ getInternalElements()

◆ getName()

◆ getReadQueue()

◆ getUnit()

◆ getValueType()

◆ getVersionNumber()

◆ interrupt()

◆ interrupt_impl()

◆ isReadable()

◆ isReadOnly()

◆ isReadTransactionInProgress()

◆ isWriteable()

◆ isWriteTransactionInProgress()

◆ makeCopyRegisterDecorator()

◆ makeUniqueId()

◆ mayReplaceOther()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ postRead()

◆ postWrite()

◆ preRead()

◆ preWrite()

◆ read()

◆ readLatest()

◆ readNonBlocking()

◆ readTransfer()

◆ readTransferNonBlocking()

◆ replaceTransferElement()

◆ setActiveException()

◆ setDataValidity()

◆ setExceptionBackend()

◆ setPersistentDataStorage()

◆ write()

◆ writeDestructively()

◆ writeTransfer()

◆ writeTransferDestructively()

Friends And Related Function Documentation

◆ ReadAnyGroup

◆ TransferGroup

Member Data Documentation

◆ _accessModeFlags

◆ _activeException

◆ _dataValidity

◆ _description

◆ _exceptionBackend

◆ _id

◆ _isInReadAnyGroup

◆ _isInTransferGroup

◆ _name

◆ _readQueue

◆ _unit