MIRA
|
An exception that occurs whenever a channel has no data. More...
#include <fw/Channel.h>
Public Member Functions | |
Channel () | |
Create channel proxy that is not assigned to a channel. More... | |
Channel (ConcreteChannel< T > *channel, ChannelAccessFlags accessFlags) | |
Is used by Framework to create a channel proxy object. More... | |
void | reset () |
Reset the proxy object so that it becomes invalid. More... | |
bool | isValid () const |
Returns true if the proxy object is valid. More... | |
void | validate () const |
Checks if the channel is valid otherwise throws an exception. More... | |
Channel Information. | |
The following methods allow to obtain information on the channel (name, type, etc). | |
const std::string & | getID () const |
Return the channel ID, its name. More... | |
int | getTypeId () const |
Returns the type id of the channel. More... | |
bool | isTyped () const |
Returns true, if the channel is typed and false, if it is untyped. More... | |
Typename | getTypename () const |
Return the typename of the channel. More... | |
void | setTypename (const Typename &type) |
Set the typename of this channel. More... | |
TypeMetaPtr | getTypeMeta () const |
Return the type meta information for this channel. More... | |
void | setTypeMeta (TypeMetaPtr meta) |
Set the type meta information for this channel. More... | |
Content information. | |
The following methods provide information on the channels content. | |
bool | isEmpty () const |
Returns if the channel is empty (no data has been published) More... | |
bool | hasSubscriber () const |
Returns true, if this channel has at least one subscriber. More... | |
bool | hasPublisher () const |
Returns true, if this channel has at least one publisher. More... | |
bool | hasSoloSlot () const |
Returns true, if this channel has one solo slot only. More... | |
std::size_t | getMaxSlots () const |
Returns the upper limit of slots that are allowed for this channel. More... | |
std::size_t | getMinSlots () const |
Returns the number slots that are guaranteed to be kept in the channel buffer. More... | |
Duration | getStorageDuration () const |
Returns the timeframe that specifies how long a slot is guaranteed to be kept in the channel buffer. More... | |
bool | isAutoIncreasingStorageDuration () const |
Returns whether the channel buffer is automatically increasing the storage duration. More... | |
std::size_t | getNrOfSlots () const |
Returns how many slots (i.e. More... | |
Accessing the channels data. | |
The Channel provides different methods for reading and writing data in different flavors. | |
ChannelRead< T > | waitForData (const Duration &timeout=Duration::infinity()) const |
Waits until data in this channel becomes available. More... | |
bool | waitForPublisher (const Duration &timeout=Duration::infinity()) const |
Waits until this channel has at least one publisher. More... | |
ChannelRead< T > | read () |
Obtains read access to the latest data element of this channel. More... | |
ChannelRead< T > | read (const Time ×tamp, SlotQueryMode mode=NEAREST_SLOT, const Duration &tolerance=Duration::infinity()) |
Obtains read access to the element at the specified timestamp. More... | |
ChannelRead< T > | read (uint32 sequenceID, const Duration &searchInterval=Duration::seconds(1)) |
Obtains read access to the element with the specified sequenceID within the given search interval If no slot with the exact sequenceID exists within the search interval an XInvalidRead exception is thrown. More... | |
ChannelRead< T > | read (const Time ×tamp, const Duration &tolerance) |
Same as above, but always takes the nearest slot. More... | |
ChannelReadInterval< T > | readInterval (const Time ×tamp, std::size_t nrSlots, std::size_t olderSlots, std::size_t newerSlots, IntervalFillMode fillMode=PREFER_NEWER) |
Obtains read access to an interval of elements before and after the requested timestamp. More... | |
ChannelReadInterval< T > | readInterval (const Time &from, const Time &to=Time::eternity()) |
Obtains read access to an interval of elements in a given time span. More... | |
ChannelWrite< T > | write () |
Obtains exclusive write access to the next free data slot of this channel. More... | |
ChannelWrite< T > | write (bool copyLatestData) |
Same as write above with an additional parameter copyLatestData that allows you to specify whether the channel should copy the latest data available into the write slot. More... | |
Stamped< T > | get () |
Returns the latest data from the channel by value. More... | |
Stamped< T > | get (const Time ×tamp, SlotQueryMode mode=NEAREST_SLOT, const Duration &tolerance=Duration::infinity()) |
Returns the data at the given time by value. More... | |
Stamped< T > | get (const Time ×tamp, Duration tolerance) |
Same as above, but always takes the nearest slot. More... | |
template<typename Filter > | |
Stamped< T > | get (const Time ×tamp, Filter &&filter) |
Returns the data at the given time by value. More... | |
template<typename U = void> | |
void | post (const Stamped< T > &value) |
Writes the specified data into the channel. More... | |
template<typename U = void> | |
void | post (Stamped< T > &&value) |
Same as above, for rvalue reference (move semantics) More... | |
template<typename U > | |
std::enable_if<!std::is_base_of_v< StampedHeader, std::decay_t< U > > >::type | post (U &&value, const Time ×tamp=Time::now()) |
Writes the specified data with the specified time stamp into the channel. More... | |
template<typename U = T> | |
std::enable_if<!std::is_void< U >::value >::type | post (const typename ParamHelper< T >::type &value, const Time ×tamp=Time::now()) |
This allows post({}, Time()); to deduce we want to post an object of the channel's type. More... | |
template<typename U = T> | |
std::enable_if<!std::is_void< U >::value >::type | post (typename ParamHelper< T >::type &&value, const Time ×tamp=Time::now()) |
Same as above, for rvalue reference (move semantics) More... | |
An exception that occurs whenever a channel has no data.
A channel is a named data container that stores data of a certain type within a buffer.
forward decl for friend decl in Channel<T>
forward declaration
Each data element in the channel is called a slot. The channel manages the access to the data and ensures safe non-blocking access across different threads. Use read() and write() to obtain access to the channel data. Write access to the channel is non blocking. This means that data can be written to the channel while other threads still maintain read access to the data. For write access the channel returns the next free slot that is not locked by any pending write or read requests. Write and read access is allowed via ChannelRead and ChannelWrite objects only. They automatically take care that the data is unlocked at the right time and that the Channel is informed about changed data.
The signaling process is as follows:
This procedure ensures that type information won't get lost although the call. ChannelSubscriber are queued within the SubscriberHandler to decouple the threads.
Implementation notes:
This class is a proxy that allows restricted (based on access rights) access to ConcreteChannel to read or/and write data to channels.
|
inline |
Create channel proxy that is not assigned to a channel.
|
inline |
Is used by Framework to create a channel proxy object.
|
inline |
Reset the proxy object so that it becomes invalid.
|
inline |
Returns true if the proxy object is valid.
Meaning if it points to a channel.
|
inline |
Checks if the channel is valid otherwise throws an exception.
XAccessViolation | If channel is not valid. |
|
inline |
Return the channel ID, its name.
|
inline |
Returns the type id of the channel.
The type id is unique only within the same process. Use getTypename() to get a portable type information.
|
inline |
Returns true, if the channel is typed and false, if it is untyped.
|
inline |
Return the typename of the channel.
Used to obtain type of the contained binary data of untyped channels.
|
inline |
Set the typename of this channel.
Can be used when the channel is untyped to specify the type of contained binary data.
|
inline |
Return the type meta information for this channel.
|
inline |
Set the type meta information for this channel.
|
inline |
Returns if the channel is empty (no data has been published)
|
inline |
Returns true, if this channel has at least one subscriber.
|
inline |
Returns true, if this channel has at least one publisher.
|
inline |
Returns true, if this channel has one solo slot only.
|
inline |
Returns the upper limit of slots that are allowed for this channel.
|
inline |
Returns the number slots that are guaranteed to be kept in the channel buffer.
|
inline |
Returns the timeframe that specifies how long a slot is guaranteed to be kept in the channel buffer.
|
inline |
Returns whether the channel buffer is automatically increasing the storage duration.
|
inline |
Returns how many slots (i.e.
data objects) are currently stored in the channel buffer.
|
inline |
Waits until data in this channel becomes available.
If a timeout is specified, the method times out if no data becomes available after the given time.
XAccessViolation | if channel has no read access rights |
[in] | timeout | Wait for this duration or forever if Duration::infinity() (default) |
|
inline |
Waits until this channel has at least one publisher.
If a timeout is specified, the method times out if no publisher becomes available after the given time.
XAccessViolation | if channel has no read access rights |
[in] | timeout | Wait for this duration or forever if Duration::infinity() (default) |
|
inline |
Obtains read access to the latest data element of this channel.
XAccessViolation | if channel has no read access rights |
XInvalidRead | when there is no data in the channel |
|
inline |
Obtains read access to the element at the specified timestamp.
If no slot with the exact timestamp exists (most of the time there will be no such slot) a slot will be chosen according to the query mode (see SlotQueryMode).
Internally calls ConcreteChannel::read().
[in] | timestamp | Timestamp of the desired slot. |
[in] | mode | Specifies whether the nearest, newer or older slot to the given timestamp should be used (default: nearest slot) |
[in] | tolerance | The max. allowed difference between the given timestamp and the best slot that was found (default: infinity) |
XAccessViolation | if channel has no read access rights |
XInvalidRead | when there is no data in the channel |
|
inline |
Obtains read access to the element with the specified sequenceID within the given search interval If no slot with the exact sequenceID exists within the search interval an XInvalidRead exception is thrown.
Internally uses readInterval(newestSlotTime - searchInterval, newestSlotTime)
[in] | sequenceID | The sequenceID of the desired slot. |
[in] | searchInterval | The interval which is searched for the sequenceID (default: 1 second) |
XAccessViolation | if channel has no read access rights |
XInvalidRead | when there is no such sequenceID within the search interval the channel |
|
inline |
Same as above, but always takes the nearest slot.
Internally calls ConcreteChannel::read().
|
inline |
Obtains read access to an interval of elements before and after the requested timestamp.
It is required that nrSlots >= olderSlots + newerSlots. The following the rules are applied:
Internally calls ConcreteChannel::readInterval().
XAccessViolation | if channel has no read access rights |
XRuntime | when there are not enough slots available. |
|
inline |
Obtains read access to an interval of elements in a given time span.
Internally calls ConcreteChannel::readInterval().
XAccessViolation | if channel has no read access rights |
|
inline |
Obtains exclusive write access to the next free data slot of this channel.
If no such slot exists the queue will grow until its maximum size. If all slots are locked and the queue has maximum size this method will block until a slot is released.
Internally calls ConcreteChannel::write().
XAccessViolation | if channel has no write access rights |
|
inline |
Same as write above with an additional parameter copyLatestData that allows you to specify whether the channel should copy the latest data available into the write slot.
This is suitable whenever the caller wants to modify the latest data partially since it allows to omit an additional read call. To use this feature the caller must obtain read access, i.e. it must be a subscriber of the channel.
Internally calls ConcreteChannel::write().
XAccessViolation | if channel has no write access rights |
|
inline |
Returns the latest data from the channel by value.
This method is provided to allow easy read access to the channel, however internally it leads to unnecessary copying of data and should be used for lightweight objects only. For large objects like range scans or images use the read() method to obtain read access without any performance penalties.
Internally calls ConcreteChannel::read().
XAccessViolation | if channel has no read access rights |
|
inline |
Returns the data at the given time by value.
This method is provided to allow easy read access to the channel, however internally it leads to unnecessary copying of data and should be used for lightweight objects only. For large objects like range scans or images use the read() method to obtain read access without any performance penalties.
Internally calls ConcreteChannel::read().
XAccessViolation | if channel has no read access rights |
Same as above, but always takes the nearest slot.
Internally calls ConcreteChannel::read().
Returns the data at the given time by value.
Moreover, this variant of the get method allows to specify a filter that is applied on the data, e.g. linear interpolation, etc.
The following example returns the value at timestamp t, where the value is linearly interpolated between two samples in the channel near the timestamp t:
If you do not need filtering or interpolation you should use the get() method without a filter or the read() method for large objects to obtain direct read access without any performance penalties.
XAccessViolation | if channel has no read access rights |
|
inline |
Writes the specified data into the channel.
This method is provided to allow easy write access to the channel, however internally it leads to unnecessary copying of data and should be used for lightweight objects only. For large objects like range scans or images use the write() method to obtain write access without any performance penalties.
XAccessViolation | if channel has no write access rights |
|
inline |
Same as above, for rvalue reference (move semantics)
|
inline |
Writes the specified data with the specified time stamp into the channel.
This method is provided to allow easy write access to the channel, however internally it leads to unnecessary copying of data and should be used for lightweight objects only. For large objects like range scans or images use the write() method to obtain write access without any performance penalties.
XAccessViolation | if channel has no write access rights |
|
inline |
This allows post({}, Time()); to deduce we want to post an object of the channel's type.
It will also make post({}) ambiguous instead of confidently posting a defaulted Stamped().
The ParamHelper indirection is required in order to avoid declaring a void reference as parameter type (for T=void).
|
inline |
Same as above, for rvalue reference (move semantics)