Class to access data shared by blocks, represented as signals. More...

#include <Signal.h>

Detailed Description

Class to access data shared by blocks, represented as signals.

Analogously to the block-algorithm corrispondence, this class introduces the signal-data corrispondence. Signals are basically the connections between blocks.

Signals do not directly translate to block's input and output. Signals are plugged into block ports, and these block ports fill the signal with data.

Briefly, core::Signal is a wrapper of a generic void* buffer.

Remarks: A signal can be plugged to more than one block port.

See also: core::Port, core::Block

Public Types
enum	DataFormat { DataFormat::NONCONTIGUOUS = 0, DataFormat::CONTIGUOUS = 1, DataFormat::CONTIGUOUS_ZEROCOPY = 2 }

Public Member Functions
	Signal (const DataFormat &dataFormat=DataFormat::CONTIGUOUS_ZEROCOPY, const Port::DataType &dataType=Port::DataType::DOUBLE)

	~Signal ()

	Signal (const Signal &other)

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

	Signal (Signal &&other)

Signal &	operator= (Signal &&other)=delete

bool	initializeBufferFromContiguous (const void *buffer, size_t len)
	Initialize the signal from a contiguous buffer. More...

bool	initializeBufferFromContiguousZeroCopy (const void *buffer, size_t len)
	Initialize the signal from a contiguous buffer without copying data. More...

bool	initializeBufferFromNonContiguous (const void const bufferPtrs, size_t len)
	Initialize the signal from a non-contiguous buffer. More...

bool	isValid () const
	Check if the signal is valid. More...

size_t	getWidth () const
	Read the width of the signal. More...

Port::DataType	getPortDataType () const
	Read the Port::DataType of the signal. More...

DataFormat	getDataFormat () const
	Read the core::Signal::DataFormat of the signal. More...

template<typename T >
T *	getBuffer ()
	Get the pointer to the buffer storing signal's data. More...

template<typename T >
const T *	getBuffer () const
	Get the pointer to the buffer storing signal's data. More...

template<typename T >
T	get (const size_t i) const
	Get a single element of the signal. More...

bool	set (const size_t index, const double data)
	Set the value of a sigle element of the buffer. More...

template<typename T >
bool	setBuffer (const T *data, const size_t length)
	Set the pointer to the buffer storing signal's data. More...

Member Enumeration Documentation

enum blockfactory::core::Signal::DataFormat

strong

Defines the format of signals supported by core::Signal. It specifies how the object should be constructed depending on how the engine stores data flowing between the different blocks.

Note: DataFormat::CONTIGUOUS_ZEROCOPY is the only format that doesn't copy data from the original buffer address into the core::Signal object. The engine is responsible of its memory management, and a core::Signal object of this type does not own any memory. On the other hand, both DataFormat::CONTIGUOUS and DataFormat::NONCONTIGUOUS copy the content of the buffer inside the Signal object. For performance reasons, prefer using DataFormat::CONTIGUOUS_ZEROCOPY since it minimizes dynamic allocations during the simulation loop.

Note: DataFormat::NONCONTIGUOUS is associated to r/o signals and methods as core::Signal::setBuffer are not allowed. It might be the candidate of input signals.

See also: core::BlockInformation::getInputPortSignal, core::BlockInformation::getOutputPortSignal

Enumerator

NONCONTIGUOUS

This data format matches the default behavior of Simulink input signals. The engine provides a pointer to an array of pointers (void**), each of them storing an element of the signal. The resulting core::Signal object will contain a copy of the content of the original buffer.

See also: core::Signal::initializeBufferFromNonContiguous

CONTIGUOUS

A core::Signal of this data format time is constructed from a pointer to a contiguous raw buffer (void*). The resulting core::Signal object will contain a copy of the content of the original buffer.

See also: core::Signal::initializeBufferFromNonContiguous

CONTIGUOUS_ZEROCOPY

This data format matches the default behavior of Simulink output signals. The engine provides a pointer to a contiguous raw buffer (void*). The resulting core::Signal object, on the contrary of the other types, will not copy the content of the original buffer, and methods such as core::Signal::getBuffer will access data directly from the memory area of the engine.

See also: core::Signal::initializeBufferFromContiguousZeroCopy

Constructor & Destructor Documentation

blockfactory::core::Signal::Signal	(	const DataFormat &	dataFormat = `DataFormat::CONTIGUOUS_ZEROCOPY`,
		const Port::DataType &	dataType = `Port::DataType::DOUBLE`
	)

blockfactory::core::Signal::~Signal ( )

blockfactory::core::Signal::Signal ( const Signal & other )

blockfactory::core::Signal::Signal ( Signal && other )

Member Function Documentation

template<typename T >

template double blockfactory::core::Signal::get< double > ( const size_t i ) const

Get a single element of the signal.

This method returns the i-th element of the handled buffer.

Template Parameters

The	data type of the returned signal. It must match configured data type.

Parameters

i	The index of the element. It should not exceed the configured width.

Returns: The i-th element of the vector if the signal is valid, or the default value of the type otherwise.

Note: It is recommended to use core::Signal::isValid before using this method.

Todo:: Switch to std::optional as soon as we switch to C++17

template<typename T >

template double * blockfactory::core::Signal::getBuffer< double > ( )

Get the pointer to the buffer storing signal's data.

The buffer is stored as a void pointer. In order to use the buffer it should be properly cast to the right data type. Be sure that the core::DataType matches the type of the buffer otherwise pointer arithmetics does not work.

If T does not match the configured data type, the returned value will be a nullptr.

Template Parameters

The	data type of the returned buffer.

Returns: The pointer to the buffer if the class is properly configured, nullptr otherwise.

Note: Always check if the pointer is not nullptr before using it.

See also: core::Signal::setBuffer

template<typename T >

const T* blockfactory::core::Signal::getBuffer ( ) const

Get the pointer to the buffer storing signal's data.

Documented in core::Signal::getBuffer

DataFormat blockfactory::core::Signal::getDataFormat ( ) const

Read the core::Signal::DataFormat of the signal.

The default type is core::DataFormat::CONTIGUOUS_ZEROCOPY.

Returns: The signal data format.

Port::DataType blockfactory::core::Signal::getPortDataType ( ) const

Read the Port::DataType of the signal.

The default type is Port::DataType::DOUBLE.

Returns: The signal data type.

size_t blockfactory::core::Signal::getWidth ( ) const

Read the width of the signal.

Returns: The signal width.

See also: Signal::isValid

bool blockfactory::core::Signal::initializeBufferFromContiguous	(	const void *	buffer,
		size_t	len
	)

Initialize the signal from a contiguous buffer.

This method allocates a new array with the same size of buffer and copies the data. In this case, the core::Signal object will own the data.

Parameters

buffer	The pointer to the original contiguous buffer.
len	The number of buffer elements.

Returns: True for success, false otherwise.

See also: core::Signal::DataFormat

bool blockfactory::core::Signal::initializeBufferFromContiguousZeroCopy	(	const void *	buffer,
		size_t	len
	)

Initialize the signal from a contiguous buffer without copying data.

This methods accepts an external contiguous buffer and holds its pointer. The data is not owned by this object.

Parameters

buffer	The pointer to the original contiguous buffer.
len	The number of buffer elements.

Returns: True for success, false otherwise.

See also: core::Signal::DataFormat

bool blockfactory::core::Signal::initializeBufferFromNonContiguous	(	const void const	bufferPtrs,
		size_t	len
	)

Initialize the signal from a non-contiguous buffer.

This method allocates a new array with the same size of bufferPtrs and copies the data. In this case, the core::Signal object will own the data. bufferPtrs points to an array of pointers. Each of these pointers points to a data element.

Parameters

bufferPtrs	The pointer to the original non-contiguous buffer.
len	The number of buffer elements.

Returns: True for success, false otherwise.

See also: core::Signal::DataFormat

bool blockfactory::core::Signal::isValid ( ) const

Check if the signal is valid.

Checks if the internal buffer is not nullptr and the configured width is greater than zero.

Returns: True for valid signal, false otherwise.

Signal& blockfactory::core::Signal::operator= ( const Signal & other )

delete

Signal& blockfactory::core::Signal::operator= ( Signal && other )

delete

bool blockfactory::core::Signal::set	(	const size_t	index,
		const double	data
	)

Set the value of a sigle element of the buffer.

Parameters

index	The index of the element to write.
data	The content of the data to write.

Returns: True for success, false otherwise.

Todo:: Port this to a template

template<typename T >

template bool blockfactory::core::Signal::setBuffer< double >	(	const T *	data,
		const size_t	length
	)

Set the pointer to the buffer storing signal's data.

This method allows changing the handled buffer. In the DataFormat::CONTIGUOUS case the data is copied inside the object. Instead, in the DataFormat::CONTIGUOUS_ZEROCOPY only the pointer to the buffer is changed.

This method is not allowed for DataFormat::NONCONTIGUOUS.

Template Parameters

The	data type of the new buffer.

Parameters

data	The new buffer address.
length	The size of the new buffer.

Returns: True if the buffer was set sucessfully, false otherwise.

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

/home/travis/build/robotology/blockfactory/sources/Core/include/BlockFactory/Core/Signal.h

Detailed Description

Public Types

Public Member Functions

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation