C++ API and example¶

1. Introduction¶

This page exist in order to extract the examples from the Doxygen documentation, Please have look at the end of this page there are all the examples.

2. C++ API and example¶

template<typename T = int> class MultiprocessTimeSeries : public internal::TimeSeriesBase<internal::MultiProcesses, int>

#include <multiprocess_time_series.hpp>

Multiprocess Time Series.

Several instances hosted by different processes, if pointing to the same shared memory segment (as specified by the segment_id), may read/write from the same underlying time series.

Public Functions

inline MultiprocessTimeSeries(std::string segment_id, size_t max_length, bool leader = true, Index start_timeindex = 0)

create a new instance pointing to the specified shared memory segment

Deprecated:: uses the factory functions create_leader or create_follower

Parameters:

segment_id – the id of the segment to point to
max_length – max number of elements in the time series
leader – if true, the shared memory segment will initialize the shared time series, and wiped the related shared memory on destruction. Instantiating a first MultiprocessTimeSeries with leader set to false will result in undefined behavior. When the leader instance is destroyed, other instances are pointing to the shared segment may crash or hang.

inline MultiprocessTimeSeries(MultiprocessTimeSeries<T> &&other) noexcept

inline std::string get_raw(const Index &timeindex)

similar to the random access operator, but does not deserialized the accessed element.

If the element is of a fundamental type (or an array of), an std::logic_error is thrown.

Public Static Functions

static inline size_t get_max_length(const std::string &segment_id): returns the max length used by a leading MultiprocessTimeSeries of the corresponding segment_id

static inline Index get_start_timeindex(const std::string &segment_id): returns the start index used by a leading MultiprocessTimeSeries of the corresponding segment_id

static inline MultiprocessTimeSeries<T> create_leader(const std::string &segment_id, size_t max_length, Index start_timeindex = 0)

returns a leader instance of MultiprocessTimeSeries<T>

Parameters:

segment_id – the id of the segment to point to
max_length – max number of elements in the time series

static inline std::shared_ptr<MultiprocessTimeSeries<T>> create_leader_ptr(const std::string &segment_id, size_t max_length, Index start_timeindex = 0): same as create_leader but returning a shared_ptr.

static inline MultiprocessTimeSeries<T> create_follower(const std::string &segment_id)

returns a follower instance of MultiprocessTimeSeries<T>.

An follower instance should be created only if a leader instance has been created first. A std::runtime_error will be thrown otherwise.

Parameters:: segment_id – the id of the segment to point to

static inline std::shared_ptr<MultiprocessTimeSeries<T>> create_follower_ptr(const std::string &segment_id): same as create_follower but returning a shared_ptr.

Protected Functions

inline void read_indexes() const

inline void write_indexes()

Protected Attributes

mutable shared_memory::array<Index> indexes_

Protected Static Functions

static inline void get_max_length_and_start_index_from_leader(const std::string &segment_id, size_t *max_length, Index *start_timeindex)

Load length and start index from leader.

Assumes that a leader time series is already running and providing this information in the shared memory.

Parameters:

segment_id – [in] The id of the segment to point to.
max_length – [out] The max. length of the time series.
start_timeindex – [out]

Throws:

std::runtime_error – If the data cannot be read from the specified shared memory segment.

template<typename T = int> class TimeSeries : public internal::TimeSeriesBase<internal::SingleProcess, int>

#include <time_series.hpp>

Threadsafe time series.

Public Functions

inline TimeSeries(size_t max_length, Index start_timeindex = 0, bool throw_on_sigint = true)

Protected Functions

inline void read_indexes() const

inline void write_indexes()

template<typename T> class TimeSeriesInterface

#include <interface.hpp>

Interface for time series.

A time_series implements \( X_{{oldest}:{newest}} \) which can safely be accessed from either multiple threads or multiple processes.

this object has the following properties:

an oldest timeindex \( oldest\),
a newest timeindex \( newest \),
a value \( X_i \) for each \( i \in \{oldest, oldest + 1 , ..., newest\} \),
a length \(length\)
and a maximum length \(maxlength\)

Public Functions

inline virtual ~TimeSeriesInterface()

virtual Index newest_timeindex(bool wait = true) const = 0: returns \( newest \) index. If argument wait is true, waits if the time_series is empty. If argument wait is false and the time series is empty, returns time_series::EMPTY immediately.

virtual Index count_appended_elements() const = 0: returns the number of element that has been contained in the queue, i.e. the number of elements that have been added from the start.

virtual Index oldest_timeindex(bool wait = true) const = 0: returns \( oldest \). waits if the time_series is empty. If argument wait is false and the time series is empty, returns time_series::EMPTY immediately.

virtual T newest_element() const = 0: returns \( X_{newest} \). waits if the time_series is empty.

virtual T operator[](const Index &timeindex) const = 0: returns \( X_{timeindex} \). waits if the time_series is empty or if \(timeindex > newest \).

virtual Timestamp timestamp_ms(const Index &timeindex) const = 0: returns the time in miliseconds when \( X_{timeindex} \) was appended. Waits if the time_series is empty or if \(timeindex > newest \).

virtual Timestamp timestamp_s(const Index &timeindex) const = 0: returns the time in seconds when \( X_{timeindex} \) was appended. Waits if the time_series is empty or if \(timeindex > newest \).

virtual bool wait_for_timeindex(const Index &timeindex, const double &max_duration_s = std::numeric_limits<double>::quiet_NaN()) const = 0: Wait until the defined time index is reached. If the input time is below the oldest time index that have been registered read an exception is return.

virtual std::size_t length() const = 0: returns the length of the time_series, i.e. \(0\) if it is empty, otherwise \(newest - oldest +1 \).

virtual std::size_t max_length() const = 0

returns the maximum length of the time serie.

Returns:: std::size_t

virtual bool has_changed_since_tag() const = 0: returns boolean indicating whether new elements have been appended since the last time the tag() function was called.

virtual void tag(const Index &timeindex) = 0: tags the current time_series, can later be used to check whether new elements have been added

virtual Index tagged_timeindex() const = 0: returns the index at which the time series has been tagged. Returns the newest timeindex if the time series has never been tagged.

virtual void append(const T &element) = 0: appends a new element to the time_series, e.g. we go from \( X_{1:10} \) to \( X_{1:11} \) (where \( X_{11}=\) element). if the time_series length is already equal to its max_length, then the oldest element is discarded, e.g. for a max_length = 10 we would go from \( X_{1:10} \) to \( X_{2:11} \).

virtual bool is_empty() const = 0: returns true if no element has ever been appended to the time series.

namespace internal

Functions

template<typename TS> void __create_python_bindings(pybind11::module &m, const std::string &classname)

template<typename P, typename T> void _create_python_bindings(pybind11::module &m, const std::string &classname)

namespace time_series

Typedefs

typedef long int Index

typedef long double Timestamp

Functions

void clear_memory(std::string segment_id)

Wipe out the corresponding shared memory.

Useful if no instances of MultiprocessTimeSeries cleared the memory on destruction. Reusing the segment id of a non-wiped shared memory may result in the newly created instance to hang.

template<typename T> void create_multiprocesses_python_bindings(pybind11::module &m, const std::string &classname): adds to the python module m a class called TimeSeries which is of typedef time_series::MultiprocessTimeSeries<T>

template<typename T> void create_python_bindings(pybind11::module &m, const std::string &classname): adds to the python module m a class called TimeSeries which is of typedef time_series::TimeSeries<T>

Variables

const Index EMPTY = -1

namespace internal

Functions

static const std::string shm_indexes ("_indexes")

static const std::string shm_elements ("_elements")

static const std::string shm_timestamps ("_timestamps")

static const std::string shm_mutex ("_mutex")

static const std::string shm_condition_variable ("_condition_variable")

file demo_multiprocess_read.cpp

#include “shared_memory/demos/item.hpp”

#include “time_series/multiprocess_time_series.hpp”

Read data from a shared timed series. This demo does nothing until demo_multiprocess_write is started. ctrl+c for exit.

Author: Vincent Berenz
Copyright: Copyright (c) 2019, Max Planck Gesellschaft.

Defines

SEGMENT_ID

TIMESERIES_SIZE

Typedefs

typedef time_series::MultiprocessTimeSeries<shared_memory::Item<10>> TimeSeries

Functions

void run(): read (and print) items written by demo_multiprocess_write

int main()

file demo_multiprocess_write.cpp

#include “shared_memory/demos/item.hpp”

#include “time_series/multiprocess_time_series.hpp”

Write data into a shared timed series. The demo demo_multiprocess_read is expected to be already running when this demo is started. Infinite hanging may occur otherwhise.

Author: Vincent Berenz

Defines

SEGMENT_ID

Typedefs

typedef time_series::MultiprocessTimeSeries<shared_memory::Item<10>> TIMESERIES

Functions

void run()

int main()

file demo_time_series.cpp

#include “real_time_tools/thread.hpp”

#include “time_series/time_series.hpp”

basic usage of time series

Author: Vincent Berenz

Functions

void *producer(void *args): Write values to the time series.

void run(): Read and display the values from the time series.

int main()

Variables

bool g_running = true

file interface.hpp

#include <cstddef>

#include <limits>

Author: Vincent Berenz license License BSD-3-Clause

file multiprocess_time_series.hpp: #include “time_series/interface.hpp”

#include “time_series/internal/base.hpp”

#include “time_series/internal/specialized_classes.hpp”

file pybind11_helper.hpp: #include <pybind11/pybind11.h>

#include <pybind11/stl.h>

#include <pybind11/stl_bind.h>

#include <type_traits>

#include “time_series/internal/specialized_classes.hpp”

#include “time_series/multiprocess_time_series.hpp”

#include “time_series/time_series.hpp”

#include “pybind11_helper.hxx”

file pybind11_helper.hxx

Functions

template<typename T> void create_multiprocesses_python_bindings(pybind11::module &m, const std::string &classname): adds to the python module m a class called TimeSeries which is of typedef time_series::MultiprocessTimeSeries<T>

template<typename T> void create_python_bindings(pybind11::module &m, const std::string &classname): adds to the python module m a class called TimeSeries which is of typedef time_series::TimeSeries<T>

file time_series.hpp

#include <chrono>

#include <cmath>

#include “real_time_tools/timer.hpp”

#include “time_series/interface.hpp”

#include “time_series/internal/base.hpp”

#include “time_series/internal/specialized_classes.hpp”

Author: Vincent Berenz license License BSD-3-Clause

page deprecated

Member time_series::MultiprocessTimeSeries< T >::MultiprocessTimeSeries (std::string segment_id, size_t max_length, bool leader=true, Index start_timeindex=0): uses the factory functions create_leader or create_follower

dir demos

dir include

dir include/time_series