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>
classtime_series
::
MultiprocessTimeSeries
: public internal::TimeSeriesBase<internal::MultiProcesses, T> - #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
-
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
- Parameters
segment_id
: the id of the segment to point tomax_length
: max number of elements in the time seriesleader
: 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.
-
MultiprocessTimeSeries
(MultiprocessTimeSeries<T> &&other) noexcept
-
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
-
size_t
get_max_length
(const std::string &segment_id) returns the max length used by a leading MultiprocessTimeSeries of the corresponding segment_id
-
Index
get_start_timeindex
(const std::string &segment_id) returns the start index used by a leading MultiprocessTimeSeries of the corresponding segment_id
-
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 tomax_length
: max number of elements in the time series
-
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.
-
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
-
std::shared_ptr<MultiprocessTimeSeries<T>>
create_follower_ptr
(const std::string &segment_id) same as create_follower but returning a shared_ptr.
Protected Functions
-
void
read_indexes
() const
-
void
write_indexes
()
Protected Attributes
-
shared_memory::array<Index>
indexes_
Protected Static Functions
-
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
[in] segment_id
: The id of the segment to point to.[out] max_length
: The max. length of the time series.[out] start_timeindex
:
- Exceptions
std::runtime_error
: If the data cannot be read from the specified shared memory segment.
-
-
template<typename
T
= int>
classtime_series
::
TimeSeries
: public internal::TimeSeriesBase<internal::SingleProcess, T> - #include <time_series.hpp>
Threadsafe time series.
Public Functions
-
TimeSeries
(size_t max_length, Index start_timeindex = 0, bool throw_on_sigint = true)
Protected Functions
-
void
read_indexes
() const
-
void
write_indexes
()
-
-
template<typename
T
>
classtime_series
::
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
-
~TimeSeriesInterface
()
-
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.
-
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.
-
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.
-
T
newest_element
() const = 0 returns \( X_{newest} \). waits if the time_series is empty.
-
T
operator[]
(const Index &timeindex) const = 0 returns \( X_{timeindex} \). waits if the time_series is empty or if \(timeindex > newest \).
-
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 \).
-
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 \).
-
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.
-
std::size_t
length
() const = 0 returns the length of the time_series, i.e. \(0\) if it is empty, otherwise \(newest - oldest +1 \).
-
std::size_t
max_length
() const = 0 returns the maximum length of the time serie.
- Return
std::size_t
-
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.
-
void
tag
(const Index &timeindex) = 0 tags the current time_series, can later be used to check whether new elements have been added
-
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.
-
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} \).
-
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
, typenameT
>
void_create_python_bindings
(pybind11::module &m, const std::string &classname)
-
template<typename
-
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
>
voidcreate_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
>
voidcreate_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
-
typedef long int
-
namespace
time_series
::
internal
Functions
-
const std::string shm_indexes ("_indexes")
-
const std::string shm_elements ("_elements")
-
const std::string shm_timestamps ("_timestamps")
-
const std::string shm_mutex ("_mutex")
-
const std::string shm_condition_variable ("_condition_variable")
-
template<typename
TS
>
void__create_python_bindings
(pybind11::module &m, const std::string &classname)
-
template<typename
P
, typenameT
>
void_create_python_bindings
(pybind11::module &m, const std::string &classname)
-
-
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
- Copyright
Copyright (c) 2019, Max Planck Gesellschaft.
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
- Copyright
Copyright (c) 2019, Max Planck Gesellschaft.
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
- Copyright
Copyright (c) 2019, Max Planck Gesellschaft.
-
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
>
voidcreate_multiprocesses_python_bindings
(pybind11::module &m, const std::string &classname)
-
template<typename
T
>
voidcreate_python_bindings
(pybind11::module &m, const std::string &classname)
-
template<typename
-
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
- Copyright
Copyright (c) 2019, Max Planck Gesellschaft.
-
file
multiprocess_time_series.cpp
- #include “time_series/multiprocess_time_series.hpp”
-
page
deprecated
-
dir
demos
-
dir
include
-
dir
src
-
dir
include/time_series