Base class for register accessors abstractors independent of the UserType. More...

#include <TransferElementAbstractor.h>

Inheritance diagram for ChimeraTK::TransferElementAbstractor:

Public Member Functions
	TransferElementAbstractor (boost::shared_ptr< TransferElement > impl)
	Construct from TransferElement implementation. More...

	TransferElementAbstractor ()=default
	Create an uninitialised abstractor - just for late initialisation. 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...

const std::type_info &	getValueType () const
	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	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...

ChimeraTK::VersionNumber	getVersionNumber () const
	Returns the version number that is associated with the last transfer (i.e. 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...

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

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

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

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

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

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

bool	isInitialised () const
	Return if the accessor is properly initialised. More...

void	replace (const TransferElementAbstractor &newAccessor)
	Assign a new accessor to this TransferElementAbstractor. More...

void	replace (boost::shared_ptr< TransferElement > newImpl)
	Alternative signature of relace() with the same functionality, used when a pointer to the implementation has been obtained directly (instead of a TransferElementAbstractor). More...

void	replaceTransferElement (const boost::shared_ptr< TransferElement > &newElement)
	Search for all underlying TransferElements which are considered identical (see mayReplaceOther()) with the given TransferElement. More...

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

TransferElementID	getId () const
	Obtain unique ID for the actual implementation of this TransferElement. More...

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

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

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

Protected Attributes
boost::shared_ptr< TransferElement >	_impl
	Untyped pointer to implementation. More...

Detailed Description

Base class for register accessors abstractors independent of the UserType.

Definition at line 28 of file TransferElementAbstractor.h.

Constructor & Destructor Documentation

◆ TransferElementAbstractor() [1/2]

ChimeraTK::TransferElementAbstractor::TransferElementAbstractor ( boost::shared_ptr< TransferElement > impl )

inlineexplicit

Construct from TransferElement implementation.

Definition at line 31 of file TransferElementAbstractor.h.

◆ TransferElementAbstractor() [2/2]

ChimeraTK::TransferElementAbstractor::TransferElementAbstractor ( )

default

Create an uninitialised abstractor - just for late initialisation.

Member Function Documentation

◆ dataValidity()

DataValidity ChimeraTK::TransferElementAbstractor::dataValidity ( ) const

inline

Return current validity of the data.

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

Definition at line 202 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ getAccessModeFlags()

AccessModeFlags ChimeraTK::TransferElementAbstractor::getAccessModeFlags ( ) const

inline

Return the AccessModeFlags for this TransferElement.

Definition at line 51 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ getDescription()

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

inline

Returns the description of this variable/register.

Definition at line 44 of file TransferElementAbstractor.h.

◆ getHardwareAccessingElements()

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

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!

Definition at line 10 of file TransferElementAbstractor.cc.

◆ getHighLevelImplElement()

const boost::shared_ptr<TransferElement>& ChimeraTK::TransferElementAbstractor::getHighLevelImplElement ( )

inline

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 145 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ getId()

TransferElementID ChimeraTK::TransferElementAbstractor::getId ( ) const

inline

Obtain unique ID for the actual implementation of this TransferElement.

This means that e.g. two instances of ScalarRegisterAccessor created by the same call to Device::getScalarRegisterAccessor() (e.g. by copying the accessor to another using NDRegisterAccessorBridge::replace()) will have the same ID, while two instances obtained by to difference calls to Device::getScalarRegisterAccessor() will have a different ID even when accessing the very same register.

Definition at line 192 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ getInternalElements()

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

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!

Definition at line 16 of file TransferElementAbstractor.cc.

◆ getName()

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

inline

Returns the name that identifies the process variable.

Definition at line 37 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ getUnit()

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

inline

Returns the engineering unit.

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

Definition at line 41 of file TransferElementAbstractor.h.

◆ getValueType()

const std::type_info& ChimeraTK::TransferElementAbstractor::getValueType ( ) const

inline

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

This can be used to determine the type at runtime.

Definition at line 48 of file TransferElementAbstractor.h.

◆ getVersionNumber()

ChimeraTK::VersionNumber ChimeraTK::TransferElementAbstractor::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.

Definition at line 83 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ interrupt()

void ChimeraTK::TransferElementAbstractor::interrupt ( )

inline

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.

This function can only be used for TransferElements with AccessMode::wait_for_new_data. Otherwise it will throw a ChimeraTK::logic_error.

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.

See Technical specification: TransferElement B.8.6

Definition at line 221 of file TransferElementAbstractor.h.

◆ isInitialised()

bool ChimeraTK::TransferElementAbstractor::isInitialised ( ) const

inline

Return if the accessor is properly initialised.

It is initialised if it was constructed passing the pointer to an implementation (a NDRegisterAccessor), it is not initialised if it was constructed only using the placeholder constructor without arguments.

Definition at line 152 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ isReadable()

bool ChimeraTK::TransferElementAbstractor::isReadable ( ) const

inline

Check if transfer element is readable.

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

Definition at line 107 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ isReadOnly()

bool ChimeraTK::TransferElementAbstractor::isReadOnly ( ) const

inline

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

it is readable but not writeable.

Definition at line 102 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ isWriteable()

bool ChimeraTK::TransferElementAbstractor::isWriteable ( ) const

inline

Check if transfer element is writeable.

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

Definition at line 112 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ read()

void ChimeraTK::TransferElementAbstractor::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 57 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ readLatest()

bool ChimeraTK::TransferElementAbstractor::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 77 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ readNonBlocking()

bool ChimeraTK::TransferElementAbstractor::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 70 of file TransferElementAbstractor.h.

◆ replace() [1/2]

void ChimeraTK::TransferElementAbstractor::replace ( boost::shared_ptr< TransferElement > newImpl )

inline

Alternative signature of relace() with the same functionality, used when a pointer to the implementation has been obtained directly (instead of a TransferElementAbstractor).

Definition at line 166 of file TransferElementAbstractor.h.

◆ replace() [2/2]

void ChimeraTK::TransferElementAbstractor::replace ( const TransferElementAbstractor & newAccessor )

inline

Assign a new accessor to this TransferElementAbstractor.

Since another TransferElementAbstractor is passed as argument, both TransferElementAbstractor will then point to the same accessor and thus are sharing the same buffer. To obtain a new copy of the accessor with a distinct buffer, the corresponding getXXRegisterAccessor() function of Device must be called.

Definition at line 160 of file TransferElementAbstractor.h.

◆ replaceTransferElement()

void ChimeraTK::TransferElementAbstractor::replaceTransferElement ( const boost::shared_ptr< TransferElement > & newElement )

Search for all underlying TransferElements which are considered identical (see mayReplaceOther()) 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 24 of file TransferElementAbstractor.cc.

◆ setDataValidity()

void ChimeraTK::TransferElementAbstractor::setDataValidity ( DataValidity valid = DataValidity::ok )

inline

Set the current DataValidity for this TransferElement.

Will do nothing if the backend does not support it

Definition at line 197 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ setPersistentDataStorage()

void ChimeraTK::TransferElementAbstractor::setPersistentDataStorage ( boost::shared_ptr< ChimeraTK::PersistentDataStorage > storage )

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 37 of file TransferElementAbstractor.cc.

◆ write()

bool ChimeraTK::TransferElementAbstractor::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 89 of file TransferElementAbstractor.h.

Here is the caller graph for this function:

◆ writeDestructively()

bool ChimeraTK::TransferElementAbstractor::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 230 of file TransferElementAbstractor.h.

Member Data Documentation

◆ _impl

boost::shared_ptr<TransferElement> ChimeraTK::TransferElementAbstractor::_impl

protected

Untyped pointer to implementation.

Definition at line 225 of file TransferElementAbstractor.h.

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

/scratch/dragon/sources/ChimeraTK-DeviceAccess/include/TransferElementAbstractor.h
/scratch/dragon/sources/ChimeraTK-DeviceAccess/src/TransferElementAbstractor.cc

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ TransferElementAbstractor() [1/2]

◆ TransferElementAbstractor() [2/2]

Member Function Documentation

◆ dataValidity()

◆ getAccessModeFlags()

◆ getDescription()

◆ getHardwareAccessingElements()

◆ getHighLevelImplElement()

◆ getId()

◆ getInternalElements()

◆ getName()

◆ getUnit()

◆ getValueType()

◆ getVersionNumber()

◆ interrupt()

◆ isInitialised()

◆ isReadable()

◆ isReadOnly()

◆ isWriteable()

◆ read()

◆ readLatest()

◆ readNonBlocking()

◆ replace() [1/2]

◆ replace() [2/2]

◆ replaceTransferElement()

◆ setDataValidity()

◆ setPersistentDataStorage()

◆ write()

◆ writeDestructively()

Member Data Documentation

◆ _impl