MIRA
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
ChannelBufferBase Class Referenceabstract

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:
Inheritance graph
[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 SlotallocateSlot ()=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 StampedHeadergetStampedHeader (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...
 
SlotrequestWriteSlot ()
 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...
 
SlotreadNewestSlot ()
 Returns the newest(latest) slot for reading, where the shared_mutex is already read locked. More...
 
SlotreadSlotAtTime (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 >
ChannelBufferBasepromote ()
 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:

Constructor & Destructor Documentation

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

virtual ~ChannelBufferBase ( )
virtual

Member Function Documentation

void cloneParameters ( const ChannelBufferBase other)
inline

Copies the parameters of other to this.

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.
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.

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.
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()
std::size_t getSize ( ) const

Returns the size of the buffer.

std::size_t getMaxSlots ( ) const

Returns the size of the max number of slots.

std::size_t getMinSlots ( ) const

Returns the size of the min number of slots.

Duration getStorageDuration ( ) const

Returns the storage duration.

bool isAutoIncreasingStorageDuration ( ) const

Returns whether the storage duration is automatically increased.

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 * >.

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 * >.

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 * >.

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 * >.

virtual void setTypename ( const Typename name)
pure virtual

Sets the Typename of the slot values.

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

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 * >.

TypeMetaPtr getTypeMeta ( ) const
inline

Returns the meta information for the slots type.

void setTypeMeta ( TypeMetaPtr  meta)
inline

Sets the meta information of the slot's type.

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 * >.

virtual Slot* allocateSlot ( )
pure virtual
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 * >.

virtual StampedHeader& getStampedHeader ( Slot s)
pure virtual

Returns a reference to the stamped header information.

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

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 * >.

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
formatVersionThe binary format version requested

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

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 * >.

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
formatVersionThe binary format version requested

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

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 * >.

virtual void readJSON ( Slot s,
JSONValue oValue 
)
pure virtual

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

Exceptions
XNotImplementedif 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 * >.

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

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

Exceptions
XNotImplementedif 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 * >.

virtual void writeJSON ( Slot s,
const JSONValue value 
)
pure virtual

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

Exceptions
XNotImplementedif 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 * >.

virtual void writeJSON ( Slot s,
JSONDeserializer value 
)
pure virtual

Writes data from an initialized json deserializer into the slot.

Exceptions
XNotImplementedif 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 * >.

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
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.
void discardWriteSlot ( Slot n)

Discards written slot.

Note
The lock of the slot is unlocked.
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.

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.

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 informations. Increases storage duration (history) automatically to serve future requests.

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.

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.

void clear ( )
protected

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

void dbgDump ( const std::string &  prefix,
bool  brief = true 
)
static void dbgCheckListIntegrity ( const ListItem list)
static
void dbgCheckIntegrity ( )

Friends And Related Function Documentation

friend struct ChannelBufferPromoterCommon
friend
friend struct ChannelBufferPromoter
friend

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