Base class that manages the slots of channels by providing read and write access to them. More...

#include <fw/ChannelBuffer.h>

Inheritance diagram for ChannelBufferBase:

[legend]

Classes
struct	ListItem
	Implements double-linked list item. More...

struct	Slot
	Container for storing a single data element in the linked list. More...

Public Member Functions
	ChannelBufferBase ()
	Constructor. More...

virtual	~ChannelBufferBase ()

void	cloneParameters (const ChannelBufferBase &other)
	Copies the parameters of other to this. More...

void	setStorageDuration (const Duration &storageDuration)
	Sets the desired storage duration (the history). More...

void	setAutoIncreaseStorageDuration (bool increase)
	Sets whether the storage duration is automatically increased on read accesses. More...

void	setMinSlots (std::size_t minSlots)
	Sets the desired min. More...

void	setMaxSlots (std::size_t maxSlots)
	Sets the max. More...

std::size_t	getSize () const
	Returns the size of the buffer. More...

std::size_t	getMaxSlots () const
	Returns the size of the max number of slots. More...

std::size_t	getMinSlots () const
	Returns the size of the min number of slots. More...

Duration	getStorageDuration () const
	Returns the storage duration. More...

bool	isAutoIncreasingStorageDuration () const
	Returns whether the storage duration is automatically increased. More...

virtual int	getTypeId () const =0
	Returns typeid of the slot values, the allocator creates. More...

virtual bool	isTyped () const =0
	Returns true, if the channel is typed and false, if it is untyped. More...

virtual bool	isPolymorphic () const =0
	Returns true if the channel has a polymorphic type. More...

virtual Typename	getTypename () const =0
	Returns the Typename of the slot values, in contrast to getTypeId() the Typename is portable and unique between different processes and operating systems. More...

virtual void	setTypename (const Typename &name)=0
	Sets the Typename of the slot values. More...

virtual TypeMetaPtr	createTypeMeta (Slot *s, MetaTypeDatabase &ioDB)=0
	Creates meta information for data in slot and stores all meta information in the given database. More...

TypeMetaPtr	getTypeMeta () const
	Returns the meta information for the slots type. More...

void	setTypeMeta (TypeMetaPtr meta)
	Sets the meta information of the slot's type. More...

virtual void	fixateType ()=0
	Calling this method will fix the type of the ChannelBuffer. More...

virtual Slot *	allocateSlot ()=0
	Creates and returns a new slot. More...

virtual void	freeSlot (Slot *s)=0
	Called to destroy the slot and free the used memory. More...

virtual StampedHeader &	getStampedHeader (Slot *s)=0
	Returns a reference to the stamped header information. More...

virtual const Buffer< uint8 > &	readSerializedValue (Slot *s)=0
	Returns a buffer containing the binary serialized data of the slot. More...

virtual const Buffer< uint8 > &	readSerializedValue (Slot *s, uint8 formatVersion, bool orLower)=0
	Returns a buffer containing the binary serialized data of the slot. More...

virtual Buffer< uint8 >	readSerializedValue (Slot *s, std::list< BinarySerializerCodecPtr > &codecs)=0
	Returns a buffer containing the binary serialized data of the slot. More...

virtual Buffer< uint8 >	readSerializedValue (Slot *s, std::list< BinarySerializerCodecPtr > &codecs, uint8 formatVersion, bool orLower)=0
	Returns a buffer containing the binary serialized data of the slot. More...

virtual void	writeSerializedValue (Slot *s, Buffer< uint8 > data)=0
	Write the given buffer (that contains binary serialized data WITHOUT the StampedHeader) to the slot. More...

virtual void	readJSON (Slot *s, JSONValue &oValue)=0
	Reads data of that slot as json representation using a default-instantiated JSONSerializer. More...

virtual void	readJSON (Slot *s, JSONValue &oValue, JSONSerializer &serializer)=0
	Reads data of that slot as json representation using the provided JSONSerializer. More...

virtual void	writeJSON (Slot *s, const JSONValue &value)=0
	Writes data in json representation into the slot, using a default-instantiated JSONDeserializer. More...

virtual void	writeJSON (Slot *s, JSONDeserializer &value)=0
	Writes data from an initialized json deserializer into the slot. More...

virtual void	writeXML (Slot *s, const XMLDom::const_iterator &node)=0
	Writes data in xml representation into the slot, using a default-instantiated XMLDeserializer and the name of the provided node. More...

Slot *	requestWriteSlot ()
	Returns a slot for writing, where the shared_mutex is already write locked. More...

bool	finishWriteSlot (Slot n, bool dropped=NULL)
	Adds written slot into buffer at the right time position. More...

void	discardWriteSlot (Slot *n)
	Discards written slot. More...

Slot *	readNewestSlot ()
	Returns the newest(latest) slot for reading, where the shared_mutex is already read locked. More...

Slot *	readSlotAtTime (const Time &timestamp, SlotQueryMode mode)
	Returns a slot at the given time according to mode. More...

void	readInterval (const Time &timestamp, std::size_t nrSlots, std::size_t olderSlots, std::size_t newerSlots, IntervalFillMode fillMode, std::list< Slot *> &oSlots)
	Reads an interval of slots. More...

void	readInterval (const Time &from, const Time &to, std::list< Slot *> &oSlots)
	Reads an interval of slots. More...

template<typename TargetType >
ChannelBufferBase *	promote ()
	Promotes this buffer to the specified target type (if required). More...

void	dbgDump (const std::string &prefix, bool brief=true)

void	dbgCheckIntegrity ()

Static Public Member Functions
static void	dbgCheckListIntegrity (const ListItem &list)

Protected Member Functions
void	clear ()
	Deletes all slots in all lists and therefore clears the whole buffer. More...

Friends
template<typename TargetType >
struct	ChannelBufferPromoterCommon

template<typename TargetType >
struct	ChannelBufferPromoter

Detailed Description

Base class that manages the slots of channels by providing read and write access to them.

It also secures the time order of the slots for reading intervals.

Design decisions:

cannot use std::list, since (C++ STL standard) std::list::splice invalidates iterators, hence we must implement our own list. (in practice SGI implementation doesn't but Visual C++ version does)
iterators in our implementation are then pointers to ChannelBufferSlot which are always valid

Constructor & Destructor Documentation

◆ ChannelBufferBase()

ChannelBufferBase ( )

inline

Constructor.

!KEEP INLINE! out of performance reasons. Creates an empty buffer with a maximum of 100 slots and an empty storage duration - meaning a history of 0

◆ ~ChannelBufferBase()

virtual ~ChannelBufferBase ( )

virtual

Member Function Documentation

◆ cloneParameters()

void cloneParameters ( const ChannelBufferBase & other )

inline

Copies the parameters of other to this.

◆ setStorageDuration()

void setStorageDuration ( const Duration & storageDuration )

Sets the desired storage duration (the history).

This method can increase the duration only. If the specified duration is smaller than a previous set duration the call will be ignored.

Note: Duration can only be increased until the maximum number of slots is reached. Use setMaxSlots() to increase maximum number of slots.

◆ setAutoIncreaseStorageDuration()

void setAutoIncreaseStorageDuration ( bool increase )

Sets whether the storage duration is automatically increased on read accesses.

If true, any read access specifying a timestamp will automatically increase the storage duration to the time difference between the timestamp and the most recent data (trying to ensure data is kept long enough for further such requests). The default is true.

◆ setMinSlots()

void setMinSlots ( std::size_t minSlots )

Sets the desired min.

number of slots for storing the history of a channel. This method can increase the min. number of slots only. Instead of specifying the min. number of slots you can also specify the desired storage duration using the setStorageDuration() method.

Note: The desired number of slots can be increased until the maximum number of slots is reached. Use setMaxSlots() to increase maximum number of slots.

◆ setMaxSlots()

void setMaxSlots ( std::size_t maxSlots )

Sets the max.

number of slots that are used for storing the history of a channel. maxSlots must at least be 1. The default is 100.

Note: There will only be as many slots as needed depending on the number of publishers and subscribers. The number of slots will also grow (history) if a storage duration is specified via setStorageDuration()

◆ getSize()

std::size_t getSize ( ) const

Returns the size of the buffer.

◆ getMaxSlots()

std::size_t getMaxSlots ( ) const

Returns the size of the max number of slots.

◆ getMinSlots()

std::size_t getMinSlots ( ) const

Returns the size of the min number of slots.

◆ getStorageDuration()

Duration getStorageDuration ( ) const

Returns the storage duration.

◆ isAutoIncreasingStorageDuration()

bool isAutoIncreasingStorageDuration ( ) const

Returns whether the storage duration is automatically increased.

◆ getTypeId()

virtual int getTypeId ( ) const

pure virtual

Returns typeid of the slot values, the allocator creates.

Implemented in PolymorphicChannelBuffer, ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ isTyped()

virtual bool isTyped ( ) const

pure virtual

Returns true, if the channel is typed and false, if it is untyped.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ isPolymorphic()

virtual bool isPolymorphic ( ) const

pure virtual

Returns true if the channel has a polymorphic type.

Implemented in PolymorphicChannelBuffer, ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ getTypename()

virtual Typename getTypename ( ) const

pure virtual

Returns the Typename of the slot values, in contrast to getTypeId() the Typename is portable and unique between different processes and operating systems.

Implemented in PolymorphicChannelBuffer, ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ setTypename()

virtual void setTypename ( const Typename & name )

pure virtual

Sets the Typename of the slot values.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ createTypeMeta()

virtual TypeMetaPtr createTypeMeta	(	Slot *	s,
		MetaTypeDatabase &	ioDB
	)

pure virtual

Creates meta information for data in slot and stores all meta information in the given database.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ getTypeMeta()

TypeMetaPtr getTypeMeta ( ) const

inline

Returns the meta information for the slots type.

◆ setTypeMeta()

void setTypeMeta ( TypeMetaPtr meta )

inline

Sets the meta information of the slot's type.

◆ fixateType()

virtual void fixateType ( )

pure virtual

Calling this method will fix the type of the ChannelBuffer.

This method currently is used by the polymorphic buffer only. It will set the type of the buffer to the type that the buffer currently has, hence it fixates the type of the buffer and the buffer can not be promoted to any other type of a derived class.

Implemented in PolymorphicChannelBuffer, ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ allocateSlot()

virtual Slot* allocateSlot ( )

pure virtual

Creates and returns a new slot.

Implemented in PolymorphicChannelBuffer, ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ freeSlot()

virtual void freeSlot ( Slot * s )

pure virtual

Called to destroy the slot and free the used memory.

Implemented in PolymorphicChannelBuffer, ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ getStampedHeader()

virtual StampedHeader& getStampedHeader ( Slot * s )

pure virtual

Returns a reference to the stamped header information.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ readSerializedValue() [1/4]

virtual const Buffer<uint8>& readSerializedValue ( Slot * s )

pure virtual

Returns a buffer containing the binary serialized data of the slot.

The serialized data does NOT contain any StampedHeader information.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ readSerializedValue() [2/4]

virtual const Buffer<uint8>& readSerializedValue	(	Slot *	s,
		uint8	formatVersion,
		bool	orLower
	)

pure virtual

Returns a buffer containing the binary serialized data of the slot.

The serialized data does NOT contain any StampedHeader information.

Parameters

formatVersion The binary format version requested

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ readSerializedValue() [3/4]

virtual Buffer<uint8> readSerializedValue	(	Slot *	s,
		std::list< BinarySerializerCodecPtr > &	codecs
	)

pure virtual

Returns a buffer containing the binary serialized data of the slot.

The serialized data does NOT contain any StampedHeader information. For serialization it will use the specified codecs.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ readSerializedValue() [4/4]

virtual Buffer<uint8> readSerializedValue	(	Slot *	s,
		std::list< BinarySerializerCodecPtr > &	codecs,
		uint8	formatVersion,
		bool	orLower
	)

pure virtual

Returns a buffer containing the binary serialized data of the slot.

The serialized data does NOT contain any StampedHeader information. For serialization it will use the specified codecs.

Parameters

formatVersion The binary format version requested

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ writeSerializedValue()

virtual void writeSerializedValue	(	Slot *	s,
		Buffer< uint8 >	data
	)

pure virtual

Write the given buffer (that contains binary serialized data WITHOUT the StampedHeader) to the slot.

Implemented in PolymorphicChannelBuffer, ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ readJSON() [1/2]

virtual void readJSON	(	Slot *	s,
		JSONValue &	oValue
	)

pure virtual

Reads data of that slot as json representation using a default-instantiated JSONSerializer.

Exceptions

XNotImplemented if not supported by the channel

Note: This method is only supported by typed channels or untyped channels with valid metadata.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ readJSON() [2/2]

virtual void readJSON	(	Slot *	s,
		JSONValue &	oValue,
		JSONSerializer &	serializer
	)

pure virtual

Reads data of that slot as json representation using the provided JSONSerializer.

Exceptions

XNotImplemented if not supported by the channel

Note: This method is only supported by typed channels or untyped channels with valid metadata.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ writeJSON() [1/2]

virtual void writeJSON	(	Slot *	s,
		const JSONValue &	value
	)

pure virtual

Writes data in json representation into the slot, using a default-instantiated JSONDeserializer.

Exceptions

XNotImplemented if not supported by the channel

Note: That this method is only supported by typed channels or untyped channels with valid metadata.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ writeJSON() [2/2]

virtual void writeJSON	(	Slot *	s,
		JSONDeserializer &	value
	)

pure virtual

Writes data from an initialized json deserializer into the slot.

Exceptions

XNotImplemented if not supported by the channel

Note: That this method is only supported by typed channels or untyped channels with valid metadata.

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ writeXML()

virtual void writeXML	(	Slot *	s,
		const XMLDom::const_iterator &	node
	)

pure virtual

Writes data in xml representation into the slot, using a default-instantiated XMLDeserializer and the name of the provided node.

Exceptions

XNotImplemented if not supported by the channel

Note: That this method is only supported by typed channels

Implemented in ChannelBuffer< void >, TypedChannelBufferBase< T >, and TypedChannelBufferBase< Object *>.

◆ requestWriteSlot()

Slot* requestWriteSlot ( )

Returns a slot for writing, where the shared_mutex is already write locked.

Implementation details:

Cycle of a slot:
   newly created (requestWriteSlot, Step ..)
    |
    v
   writing list
    |finish    |
    v          |discard
   ring buffer |
    |read      |
    v          v
   mWaitingOrFree
    |
    v

◆ finishWriteSlot()

bool finishWriteSlot	(	Slot *	n,
		bool *	dropped = `NULL`
	)

Adds written slot into buffer at the right time position.

Returns true, if the new Slot value is now the newest value in the buffer. dropped is set to true, if a slot with the same timestamp already exists and hence the slot was discarded.

Note: The lock of the slot is unlocked.

◆ discardWriteSlot()

void discardWriteSlot ( Slot * n )

Discards written slot.

Note: The lock of the slot is unlocked.

◆ readNewestSlot()

Slot* readNewestSlot ( )

Returns the newest(latest) slot for reading, where the shared_mutex is already read locked.

Returns NULL if no slot for reading is available.

◆ readSlotAtTime()

Slot* readSlotAtTime	(	const Time &	timestamp,
		SlotQueryMode	mode
	)

Returns a slot at the given time according to mode.

Returns NULL if no slot exists. See mira::Channel::read() for more informations. Increases storage duration (history) automatically to serve future requests.

◆ readInterval() [1/2]

void readInterval	(	const Time &	timestamp,
		std::size_t	nrSlots,
		std::size_t	olderSlots,
		std::size_t	newerSlots,
		IntervalFillMode	fillMode,
		std::list< Slot *> &	oSlots
	)

Reads an interval of slots.

See mira::Channel::readInterval for more information. Increases storage duration (history) automatically to serve future requests.

Exceptions

XInvalidRead if not enough data slots available in channel

◆ readInterval() [2/2]

void readInterval	(	const Time &	from,
		const Time &	to,
		std::list< Slot *> &	oSlots
	)

Reads an interval of slots.

See mira::Channel::readInterval for more informations. Increases storage duration (history) automatically to serve future requests.

Exceptions

XInvalidParameter if from > to

◆ promote()

ChannelBufferBase * promote ( )

Promotes this buffer to the specified target type (if required).

This method may create and return a new ChannelBuffer of the desired TargetType. In this case the original buffer should be destroyed by the caller. In some other cases when no new buffer needs to be created the method returns a pointer to this buffer itself.

◆ clear()

void clear ( )

protected

Deletes all slots in all lists and therefore clears the whole buffer.

◆ dbgDump()

void dbgDump	(	const std::string &	prefix,
		bool	brief = `true`
	)

◆ dbgCheckListIntegrity()

static void dbgCheckListIntegrity ( const ListItem & list )

static

◆ dbgCheckIntegrity()

void dbgCheckIntegrity ( )

Friends And Related Function Documentation

◆ ChannelBufferPromoterCommon

friend struct ChannelBufferPromoterCommon

friend

◆ ChannelBufferPromoter

friend struct ChannelBufferPromoter

friend

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

framework/include/fw/ChannelBuffer.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ChannelBufferBase()

◆ ~ChannelBufferBase()

Member Function Documentation

◆ cloneParameters()

◆ setStorageDuration()

◆ setAutoIncreaseStorageDuration()

◆ setMinSlots()

◆ setMaxSlots()

◆ getSize()

◆ getMaxSlots()

◆ getMinSlots()

◆ getStorageDuration()

◆ isAutoIncreasingStorageDuration()

◆ getTypeId()

◆ isTyped()

◆ isPolymorphic()

◆ getTypename()

◆ setTypename()

◆ createTypeMeta()

◆ getTypeMeta()

◆ setTypeMeta()

◆ fixateType()

◆ allocateSlot()

◆ freeSlot()

◆ getStampedHeader()

◆ readSerializedValue() [1/4]

◆ readSerializedValue() [2/4]

◆ readSerializedValue() [3/4]

◆ readSerializedValue() [4/4]

◆ writeSerializedValue()

◆ readJSON() [1/2]

◆ readJSON() [2/2]

◆ writeJSON() [1/2]

◆ writeJSON() [2/2]

◆ writeXML()

◆ requestWriteSlot()

◆ finishWriteSlot()

◆ discardWriteSlot()

◆ readNewestSlot()

◆ readSlotAtTime()

◆ readInterval() [1/2]

◆ readInterval() [2/2]

◆ promote()

◆ clear()

◆ dbgDump()

◆ dbgCheckListIntegrity()

◆ dbgCheckIntegrity()

Friends And Related Function Documentation

◆ ChannelBufferPromoterCommon

◆ ChannelBufferPromoter