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<size_t NUM_CHECKPOINTS, bool ENABLED = true> class CheckpointTimer

#include <checkpoint_timer.hpp>

Timer to measure code execution time with “checkpoints”.

This timer is meant to be used for measuring execution time of a loop. It measures time between calls of the start method, so by calling this at the beginning of the loop, you get the execution time of the full iteration. Further, you can define “checkpoints” within the loop to measure time of separate steps in the loop. Call the checkpoint method after the code that is associated with it. For each checkpoint, the time elapsed since the last checkpoint is measured (start counts as a checkpoint in this regard).

Example:

    // set second template argument to false to disable timer
    real_time_tools::CheckpointTimer<3, true> timer;

    for (int i = 0; i < 1000; i++)
    {
        timer.start();

        init();
        timer.checkpoint("initialize");

        do_some_stuff();
        timer.checkpoint("do some stuff");

        write_log();
        timer.checkpoint("logging");

        // print the timing results every 100 iterations
        if (i % 100 == 0 && i > 0)
        {
            timer.print_statistics();
        }
    }

Template Parameters:

NUM_CHECKPOINTS – Number of checkpoints.
ENABLED – Set to false, to disable timer. Method calls will have no effect (and should hopefully be optimized away by the compiler).

Public Functions

CheckpointTimer()

void start(): Start timer iteration.

void checkpoint(const std::string &checkpoint_name)

Set checkpoint for time measurement.

Measures time from the last call of start() or checkpoint() until this call. The given name is used when printing the results.

Parameters:: checkpoint_name – Name of the checkpoint (used for printing results)

void print_statistics() const: Print results of time measurements.

Private Members

std::array<real_time_tools::Timer, NUM_CHECKPOINTS + 1> timers_

Timers used for the different checkpoints.

Index 0 is used for the total duration.

std::array<std::string, NUM_CHECKPOINTS + 1> checkpoint_names_: Names of the checkpoints.

size_t current_checkpoint_ = 1: Index of the current checkpoint.

class FrequencyManager

#include <frequency_manager.hpp>

Class to have threads / loops running at a desired frequency.

Public Functions

FrequencyManager(double frequency)

FrequencyManager()

void set_frequency(double frequency)

void set_period(double period_s)

double predict_sleeping_time() const

bool wait()

waits for the time such that successive calls to wait will result in wait being called at the desired frequency

Returns:: true if the desired frequency could be enforced

Private Members

double period_ms_

double previous_time_ms_

class PortConfig

#include <usb_stream.hpp>

Simple config class that encapsulate the port parameters for a USB port.

This should cover enough paramter to setup the USB port for the imu_3DM_GX3_25, imu_3DM_GX3_45 and the imu_3DM_GX5 in xenomai, rt_preempt and ubuntu (potentially MacOS: non posix).

Public Types

enum StopBits

This is if one wants 1 or 2 stop bits.

Values:

enumerator one

enumerator two

enum DataBits

This correspond to the number of data bits echanged.

Values:

enumerator cs7

enumerator cs8

Public Functions

int get_bauderate()

Get the _bauderate object.

Returns:: int

Public Members

bool rts_cts_enabled_

Enabling/Disabling rts cts.

TODO: look for what is rts cts

bool parity_: Use or not a parity bit.

StopBits stop_bits_

Defines the choice of the stop bits.

(see enum StopBits)

bool prepare_size_definition_: Defines if the port should prepare the size definition.

DataBits data_bits_

Defines the number of bits echanged.

(see enum DataBits)

int baude_rate_

Defines the BaudeRate to be used.

(see enum BaudeRate)

class RealTimeCheck

#include <realtime_check.hpp>

super simple class for checking if thread ever lost realtime.

simply measure frequency between two calls to the tick function.

Public Functions

RealTimeCheck(double target_frequency, double switch_frequency)

Construct a new RealTimeCheck object.

Parameters:

target_frequency – is the loop frequency.
switch_frequency – is the admissible frequency.

void tick(): inform the instance of this class that an iteration passed

bool was_realtime_lost() const: true if realtime was lost at least once (frequency between two ticks was below target frequencies)

bool get_statistics(int &ticks, int &switchs, double &target_frequency, double &switch_frequency, double &average_frequency, double &current_frequency, double &worse_frequency): return true if statistics are available, false otherwise (false is returned is tick has never been called or if ticks reached maximum integer value) switchs in the number of time realtime was lost.

double get_average_frequency(): return the averaged observed frequency if statistics are available, -1 otherwise (false is returned is tick has never been called or if ticks reached maximum integer value).

double get_current_frequency() const: returns observed frequency after last call to tick

void print(): Display the results of the frequency measurement.

Private Members

bool started: true if tick has been called once

std::chrono::high_resolution_clock::time_point start_time: time at which tick was called first

std::chrono::high_resolution_clock::time_point last_tick: last time system was ticked

double target_frequency: frequency at which ticks are expected

double epsilon: small quantity

uint ticks: number of iterations

uint switchs: number of time realtime was lost (target frequency not respected between two ticks)

double average_frequency: average frequency

double worse_frequency: worse frequency ever experienced

double switch_frequency: nb of switches will increase by 1 each time measured frequency below this value

double current_frequency: latest frequency that was measured

std::mutex mutex: multithreading safety

class RealTimeMutex

#include <mutex.hpp>

This class uses the real-time API of xenomai and posix to implement mutexes.

Public Functions

inline RealTimeMutex(std::string mutex_id = ""): Construct a new RealTimeMutex object.

inline ~RealTimeMutex(): Destroy the RealTimeMutex object.

inline void lock(): lock the mutex.

inline void unlock(): unlock the mutex

Private Members

RealTimeMutex_t mutex_: This is the object which type chenge according to the OS this code is compiled.

std::string mutex_id_: Save the mutex id internally.

class RealTimeThread

#include <thread.hpp>

This class allows you to spawn thread.

Its parameter are defined above.

Public Functions

RealTimeThread(): Construct a new ThreadInfo object.

RealTimeThread(const real_time_tools::RealTimeThread &other) = delete: We do not allow copies of this object.

~RealTimeThread(): Destroy the RealTimeThread object.

int create_realtime_thread(void *(*thread_function)(void*), void *args = nullptr, )

create_realtime_thread spawns a real time thread if the OS allows it.

Parameters:

thread_function – [in] the executing function for the thread.
args – [in] arguments to be passed to the thread.

Returns:

the error code.

int join()

join join the real time thread

Returns:: the error code.

void block_memory()

block_memory block the current and futur memory pages.

see https://wiki.linuxfoundation.org/realtime/documentation/howto/applications/memory#memory-locking for further explanation.

Public Members

RealTimeThreadParameters parameters_: Paramter of the real time thread.

class RealTimeThreadParameters

#include <thread.hpp>

This class is a data structure allowing the user to share configurations among threads.

These parameter allows you to generate real threads in xenomai and rt_preempt. The same code is compatible with Mac and ubuntu but will run non-real time threads.

warning : initial version, copy pasted from : https://wiki.linuxfoundation.org/realtime/documentation/howto/applications/application_base I did not study things now, so this likely needs improvement (alternative: https://rt.wiki.kernel.org/index.php/Threaded_RT-application_with_memory_locking_and_stack_handling_example) note: if failed as mlockall, run executable with sudo or be part of the real_time group or xenomai group.

Public Functions

inline RealTimeThreadParameters(): Construct a new RealTimeThreadParameters object.

inline ~RealTimeThreadParameters(): Destroy the RealTimeThreadParameters object.

Public Members

std::string keyword_: Used in xenomai to define the thread id.

int priority_: Defines the thread priority from 0 to 100.

int stack_size_: Define the stack size.

std::vector<int> cpu_id_

Define the cpu affinity.

Which means on which cpu(s) the thread is going to run

int dedicated_cpu_id_: indicate on which cpu the thread will run (xenomai only)

int delay_ns_

Todo:: Unknow Xenomai parameter

bool block_memory_

Defines if the thread should block the memory in a “page” or if several pages can be use.

Switching memory page is time consumming and a non real time operation.

int cpu_dma_latency_

Maximum desired latency of the CPU in microseconds.

Set to 0 to get best real-time performance. Set to any negative value if you do not want the thread to change the CPU latency.

template<typename Type, size_t SIZE> class SingletypeThreadsafeObject

#include <threadsafe_object.hpp>

The SingletypeThreadsafeObject is a thread safe object.

Template Parameters:

Type – is the data type to store in the buffer.
SIZE – is the size of the buffer. It is better to know it at compile time to be 100% real time safe.

Public Functions

SingletypeThreadsafeObject(): Construct a new SingletypeThreadsafeObject object.

SingletypeThreadsafeObject(const std::vector<std::string> &names)

Construct a new SingletypeThreadsafeObject object.

Parameters:: names –

void wait_for_update(const size_t &index) const

Wait until the data at the given index is modified.

Parameters:: index –

inline void wait_for_update(const std::string &name) const

Wait until the data at the given name is modified.

Parameters:: name –

size_t wait_for_update() const

Wait unitl any data has been changed and return its index.

Returns:: size_t

inline size_t size()

Getters.

get size.

Returns:: size_t

inline Type get(const size_t &index = 0) const

Get the data by its index in the buffer.

Parameters:: index –
Returns:: Type

inline Type get(const std::string &name) const

Get the data by its name in the buffer.

Parameters:: name –
Returns:: Type

template<int INDEX = 0> inline Type get() const

Get the data by its index in the buffer.

Index is solved during compile time

Template Parameters:: INDEX=0 –
Returns:: Type

void set(const Type &datum, const size_t &index = 0)

Setters.

Set one element at a designated index.

Parameters:

datum –
index –

template<int INDEX = 0> inline void set(Type datum)

Set one element at a designated index.

Warning the index is resolved at compile time. This is used for backward comaptibility.

Todo:: ”This is used for backward comaptibility.”, Manuel Which bakward?

Template Parameters:: INDEX=0 –
Parameters:: datum –

inline void set(const Type &datum, const std::string &name)

Set one element using at a designated name.

Internally this name is map to an index.

Parameters:

datum –
name –

Private Members

std::shared_ptr<std::array<Type, SIZE>> data_: This is the data buffer.

std::shared_ptr<std::array<size_t, SIZE>> modification_counts_: This is counting the data modification occurences for each individual buffers.

std::shared_ptr<size_t> total_modification_count_

This is counting the all data modification occurences for all buffer.

/todo Can’t we just some the modification_counts_ array whenever needed?

std::map<std::string, size_t> name_to_index_: This is the map that allow to deal with data by their names.

mutable std::shared_ptr<std::condition_variable> condition_: This condition variable is used to wait untils any data has been changed.

mutable std::shared_ptr<std::mutex> condition_mutex_: This is the mutex of the condition varaible.

mutable std::shared_ptr<std::array<std::mutex, SIZE>> data_mutexes_: These are the individual mutexes of each data upon setting and getting.

class Spinner

#include <spinner.hpp>

Class to have threads / loops running at a desired frequency.

Public Functions

Spinner()

inline void set_period(double period)

set_period sets the period of the loop in !!seconds!!

Parameters:: period – in seconds.

inline void set_frequency(double frequency)

Set the frequency of the loop [Hz].

Parameters:: frequency –

void initialize(): To be called at the beginning of the loop if the spinner is not created just before.

void spin(): spin waits for the time such that successive calls to spin will result in spin being called at the desired frequency

double predict_sleeping_time(): Predict the time the current thread is going to sleep.

Private Members

double period_sec_: period_sec_ is the period of the loop in seconds

double next_date_sec_: next_date_sec_ is the date when the loop needs to wake up.

template<typename Type> class ThreadsafeHistoryInterface

#include <threadsafe_object.hpp>

This is a template abstract interface class that define a data history.

This re-writting of the vector style class is thread safe. So it allows the user to use the object without having to deal with mutexes nor condition variables. This class is not used so far.

Template Parameters:: Type – is the type of the data to store.

Private Functions

inline virtual Type get_next(size_t id) const

Get the element after the one with the given id.

if there is no newer element, then wait until one arrives.

Parameters:: id – is the index of the element in the buffer.
Returns:: Type the next element.

virtual size_t get_next_id(size_t id) const = 0

inline virtual Type get_newest() const

Get the newest value, this function waits if it is empty.

Returns:: Type the newest element.

virtual size_t get_newest_id() const = 0

get_newest_id

Returns:: size_t

virtual Type get(size_t id) const = 0

Get the value whith a specific id.

Parameters:: id –
Returns:: Type

virtual void add() = 0

I guess this is to add a value but with no argument?

Todo:: Manuel, could you delete this class or provide an implementation?

template<typename ...Types> class ThreadsafeObject

#include <threadsafe_object.hpp>

This object can have several types depending on what ones want to store.

Template Parameters:: Types –

Public Types

using Type = typename std::tuple_element<INDEX, std::tuple<Types...>>::type

Define a specific “Type” which permit a more readable code.

Template Parameters:: INDEX –

Public Functions

ThreadsafeObject(): Construct a new ThreadsafeObject object.

void wait_for_update(unsigned index) const

Wait until the data with the deignated index is changed.

Parameters:: index –

template<unsigned INDEX = 0> inline void wait_for_update() const

Wait until the data with the designated index is changed.

Template Parameters:: INDEX=0 –

size_t wait_for_update() const

Wait until any data has been changed.

Returns:: size_t

template<int INDEX = 0> Type<INDEX> get() const

Getters.

Get the data with the designated index. The index is resolved at compile time.

Template Parameters:: INDEX=0 –
Returns:: Type<INDEX>

template<int INDEX = 0> void set(Type<INDEX> datum)

Setters.

Set the data with the designated index. The index is resolved at compile time.

Template Parameters:: INDEX=0 –
Parameters:: datum –

template<int INDEX> ThreadsafeObject<Types...>::template Type<INDEX> get() const

template<int INDEX> void set(ThreadsafeObject<Types...>::Type<INDEX> datum)

Setters.

Set the data with the designated index. The index is resolved at compile time.

Template Parameters:: INDEX=0 –
Parameters:: datum –

Public Static Attributes

static const std::size_t SIZE = sizeof...(Types): Define the size of the different types.

Private Members

std::shared_ptr<std::tuple<Types...>> data_: the actual data buffers.

mutable std::shared_ptr<std::condition_variable> condition_: a condition variable that allow to wait until one data has been changed in the buffer.

mutable std::shared_ptr<std::mutex> condition_mutex_: The mutex of the condition variable.

std::shared_ptr<std::array<size_t, SIZE>> modification_counts_: This is counting the data modification occurences for each individual buffers.

std::shared_ptr<size_t> total_modification_count_

This is counting the all data modification occurences for all buffer.

/todo Can’t we just some the modification_counts_ array whenever needed?

std::shared_ptr<std::array<std::mutex, SIZE>> data_mutexes_: These are the individual mutexes of each data upon setting and getting.

class Timer

#include <timer.hpp>

The timer class is a simple time measurement class that measure between tic and tac and with a memory buffer of a certain size.

Public Functions

Timer(): timer constructor

void tic()

tic measures the time when it is called.

This is to be used with the tac method that will return the time elapsed between tic and tac.

double tac()

tac is to be used after tic has been called.

Returns:: the duration in seconds between the call of tic() and the call of tac(). if tic() has not been called previously this will return nan

double tac_tic(): this is like a tac() followed by a tic(), making sure the previous tac_time becomes the tic_time

void log_time_interval(double time_interval)

Save the time interval measured.

Parameters:: time_interval –

void dump_measurements(std::string file_name) const

IOSTREAM functions.

dump_tic_tac_measurements writes in a file the time elapsed between every tick

Parameters:: file_name – is the path to the file.

void print_statistics() const: print_statistics display in real time the statistics of the time measurements acquiered so far.

inline void set_memory_size(const unsigned memory_buffer_size)

SETTERS.

set_memory_size sets the buffer size. It resets all value of the buffer to zero. !! WARNING non real time method. !!

Parameters:: memory_buffer_size – is the size use to reset the size of the

inline void set_name(std::string name)

set_name modify the name of the object for display purposes.

Parameters:: name – is the new name of the object.

inline double get_min_elapsed_sec() const

GETTERS.

get_min_elapsed_sec

Returns:: a copy of the minimum elapsed times

inline double get_max_elapsed_sec() const

get_max_elapsed_sec

Returns:: a copy of the maximum elapsed times

inline double get_avg_elapsed_sec() const

get_avg_elapsed_sec

Returns:: a copy of the average elapsed time

inline double get_std_dev_elapsed_sec() const

get_std_dev_elapsed_sec

Returns:: a copy of the standard deviation of the elapsed times

Public Static Functions

static double get_current_time_sec()

Some utilities.

get_current_time_sec gives the current time in double and in seconds

Returns:

static inline double get_current_time_ms()

get_current_time_ms gives the current time in double and in milli seconds

Returns:

static int sleep_microseconds(int sleep_duration_us)

puts the current thread to sleep for the duration of “sleep_duration_us” micro-seconds.

Parameters:: sleep_time_us – is the sleeping duration asked in micro-seconds.
Returns:: 0 on success, error code otherwise

static void sleep_sec(const double &sleep_time_sec)

sleep_sec puts the current thread to sleep for the duration of “sleep_time_sec” seconds.

Parameters:: sleep_time_sec – is the sleeping duration asked in seconds.

static inline void sleep_ms(const double &sleep_time_ms)

sleep_ms puts the current thread to sleep for the duration of “sleep_time_sec” seconds.

Parameters:: sleep_time_ms – is the sleeping duration asked in seconds.

static void sleep_until_sec(const double &date_sec)

sleep_until_sec puts the threads to sleep until the date “date_sec” is reached.

Parameters:: date_sec – is the date until when to sleep in seconds.

static void timespec_add_sec(struct timespec &date_spec, const double duration_sec)

timespec_add_sec posix type of a date in time.

Parameters:

date_spec – is the date to be changed
duration_sec – the duration to be added to “t” in seconds

static void sec_to_timespec(double date_sec, struct timespec &date_spec)

sec_to_timespec converts a double representing the time in seconds to a struct timespec.

Parameters:

date_sec – [in] is the time in sec to be converted.
date_spec – [out] is the converted structure.

static std::string get_current_date_str(): get_current_date_str get the current date and format it in a string with “year_month_day_hour_minute_sec”

Protected Attributes

double tic_time_: tic_time_ time at which tic() was called

std::deque<double> time_measurement_buffer_: time_measurement_buffer_ this is a chained list of double

long unsigned count_: count_time_buffer_ is a counter that manages the time_measurement_buffer_ fill in.

unsigned memory_buffer_size_: memory_buffer_size_ is the max size of the memory buffer.

double min_elapsed_time_: min_elapsed_time_ is the minimum measured elapsed time

double max_elapsed_time_: max_elapsed_time_ is the maximum measured elapsed time

double avg_elapsed_time_: avg_elapsed_time_ is the average measured elapsed time

double second_moment_elapsed_time_: avg_elapsed_time_ is the second moment measured elapsed time

std::string name_: name_ of the timer object

class UsbStream

#include <usb_stream.hpp>

This class has for purpose to interact with devices and files alike as the linux philosophie does.

Depending on the current Operating system it uses the available real time APIs.

Public Functions

UsbStream(): Construct a new fstream object.

~UsbStream(): Destroy the fstream object.

bool open_device(const std::string &file_name)

This method allows you to open a port or a file.

Parameters:: file_name –

bool set_port_config(const PortConfig &user_config)

Set the _port_config object parametrize the port configuration.

Parameters:: user_config – is the configuration of the port. (see struct PortConfig)
Returns:: true
Returns:: false

bool close_device()

Stop the device communication.

Returns:: true success
Returns:: false problem occured

bool read_device(std::vector<uint8_t> &msg, const bool stream_on = true)

Read the port or the file.

Reports error if read bytes is not equal to expected bytes.

Parameters:

msg – is the command sent before this command was executed.
stream_on – define if we just read on the fly or we wait until we get the correct amount of data.

Returns:

true

Returns:

false

ssize_t read_device_raw(std::vector<uint8_t> &msg, const bool stream_on = true, const size_t start_location = 0)

Read the port or the file.

Does not check if read bytes is equal to expected bytes.

Parameters:

msg – is the command sent before this command was executed.
stream_on – define if we just read on the fly or we wait until we get the correct amount of data.
start_location – is the index in msg that we want to start reading to. This is for when you want to keep a portion of the already existing data: For example, when you are have read a partial message and need to get the rest while keeping the first part.

Returns:

Number of bytes read or -1 if failure.

bool write_device(const std::vector<uint8_t> &msg)

Write msg in the port or the file.

Returns:: true success
Returns:: false problem occured

bool activate_stream_mode()

Activate the stream mode.

The read method is not blocking.

Returns:: true success
Returns:: false problem occured

bool set_poll_mode_timeout(double timeout_in_second)

Set the poll mode timeout.

The read_device method is blocking until timeout.

Returns:: true success
Returns:: false problem occured

bool flush(int duration_ms = 150)

Flush the current port.

Returns:: true
Returns:: false

Public Static Functions

static std::string msg_debug_string(const std::vector<uint8_t> &msg, long int until = -1)

Display the uint8_t message in hexadecimal format.

Parameters:

msg – is the message to be displayed
until – is a bound on the number of displayed bytes. “-1” means display all.

Returns:

std::string the debug string

static bool test_msg_equal(const std::vector<uint8_t> &msg1, const std::vector<uint8_t> &msg2)

Test if two message are the same or not.

Parameters:

msg1 –
msg2 –

Returns:

true

Returns:

false

Private Members

std::string file_name_

Private methods.

Attributes This is the path tot the device file

int file_id_: This is the port id.

ssize_t return_value_: This is the return value of the different POSIX/Xenomai methods.

bool timeout_set_: Verify that the timeout value has been set.

double timeout_: The timeout for the poll mode in seconds.

std::vector<uint8_t> buffer_: Internal buffer that is supposed to be much bigger than the message sent or received to avoid memory problems.

namespace real_time_tools

Typedefs

typedef std::mutex *RealTimeMutex_t: Alias for the real time mutex.

typedef std::condition_variable rt_cond: Alias for the real time condition variable.

Functions

std::string get_log_dir(std::string app_name)

Get the logging directory based on a specific application.

It creates a direction in $HOME/app_name/YEAR_MONTH_DAY_HOUR_SECOND/ and return the absolute path of this. It allows the user to dump data in different folders everytime the user launch the application.

Parameters:: app_name – is the application name
Returns:: std::string the absolute path to the log directory

bool create_directory(std::string path)

Create a directory.

Parameters:: path – is the path to be created
Returns:: true if everything went well
Returns:: false if a problem occur

std::string get_home_dir()

Get the home directory path.

Returns:: std::string the home directory absolute path ending with a “/”

bool fix_current_process_to_cpu(std::vector<int> &cpu_affinities, int pid)

Pin an executing process to a specific CPU in order to avoid jumps between CPUs.

Parameters:

cpu_affinities – is the index of the CPU one wants to pin the process on.
pid – is the PID of the current process.

Returns:

true if everything went well.

Returns:

false otherwise

bool set_cpu_dma_latency(int max_latency_us)

Set the _cpu_dma_latency objectWe can set the maximum CPU latency for processes in micro seconds.

Parameters:: max_latency_us – is the maximum latency in micro-seconds.
Returns:: true if everything went well.
Returns:: false if something went wrong.

file demo_checkpoint_timer.cpp

#include <real_time_tools/checkpoint_timer.hpp>

#include <real_time_tools/timer.hpp>

License:: BSD 3-clause

Copyright: Copyright (c) 2020, New York University and Max Planck Gesellschaft

Functions

void init(): Dummy function.

void do_some_stuff(): Dummy function.

void write_log(): Dummy function.

int main(): Simple example on how to use the CheckpointTimer in a loop.

file demo_realtime_check.cpp

#include “real_time_tools/realtime_check.hpp”

#include “real_time_tools/thread.hpp”

#include “real_time_tools/timer.hpp”

Check the real time capbilites of a loop.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

Functions

THREAD_FUNCTION_RETURN_TYPE thread_function(void*): Real time thread that measure the spinning frequency and do some basic operation

int main(int, char*[]): Create a real time thread and measure the frequency of the thread.

file demo_realtime_strict_check.cpp

#include “real_time_tools/realtime_check.hpp”

#include “real_time_tools/thread.hpp”

Check the real time capbilites of a loop.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

Typedefs

typedef std::chrono::high_resolution_clock my_clock: define an alias for the clock

Functions

THREAD_FUNCTION_RETURN_TYPE thread_function(void*): this function is executed in a real_time_thread.

int main(int, char*[]): This demos show the used of the strict check of the real time loop.

file demo_spinner.cpp

#include “real_time_tools/realtime_check.hpp”

#include “real_time_tools/spinner.hpp”

#include “real_time_tools/thread.hpp”

Demo of the spinner class usage.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

Functions

THREAD_FUNCTION_RETURN_TYPE thread_function(void*): implement a real time thread checking the timing of the loop

int main(int, char*[]): This a demo on how to use the RealTimeCheck class.

file demo_thread.cpp

#include “real_time_tools/thread.hpp”

#include “real_time_tools/timer.hpp”

Mininal thread example.

Author: Vincent Berenz license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2020-01-02

Functions

THREAD_FUNCTION_RETURN_TYPE thread_function(void*)

int main()

file demo_timing.cpp

#include “real_time_tools/realtime_check.hpp”

#include “real_time_tools/spinner.hpp”

#include “real_time_tools/thread.hpp”

#include “real_time_tools/timer.hpp”

Demo of the Timer class usage.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

Functions

THREAD_FUNCTION_RETURN_TYPE thread_function(void*): Real time thread presenting the use of the Timer class.

int main(int, char*[]): Launch a real time thread presenting the use of the Timer class.

file demo_usb_stream_imu_3DM_GX3_25.cpp

#include “real_time_tools/timer.hpp”

#include “real_time_tools/usb_stream.hpp”

Testing imu connection directly via the drivers. See test_interface in the same package for an example of the API.

Author: Vincent Berenz (vincent.brenz@tuebingen.mpg.de)
Version: 0.1
Date: 2019-05-09

Functions

void continuous_mode_on(real_time_tools::UsbStream &usb_stream, bool stream_mode)

Send the message that set the imu into stream mode or not.

Parameters:

usb_stream – is the usb interface.
stream_mode – start or stop the stream mode.

bool is_continuous_mode_on(real_time_tools::UsbStream &usb_stream, bool stream_mode)

Check the mode of the imu.

Parameters:

usb_stream – usb communication interface.
stream_mode – read the socket in stream mode or not.

Returns:

true imu is in stream mode

Returns:

false imu is in idle mode

void continuous_mode_off(real_time_tools::UsbStream &usb_stream, bool stream_mode)

Set the imu into idle mode.

Parameters:

usb_stream –
stream_mode –

void reset(real_time_tools::UsbStream &usb_stream, bool stream_mode)

Reset the imu.

Parameters:

usb_stream –
stream_mode –

int main(int argc, char **argv)

Example on how to use the usb interface using an imu.

Parameters:

argc –
argv –

Returns:

int

file checkpoint_timer.hpp

#include <array>

#include <iostream>

#include <string>

#include “timer.hpp”

#include “checkpoint_timer.hxx”

Implementation of the CheckpointTimer class.

License:: BSD 3-clause

Copyright: Copyright (c) 2020, New York University and Max Planck Gesellschaft

file checkpoint_timer.hxx

Implementation of the CheckpointTimer class.

License:: BSD 3-clause

License:: BSD 3-clause

Copyright: Copyright (c) 2020, New York University and Max Planck Gesellschaft
Copyright: Copyright (c) 2020, New York University and Max Planck Gesellschaft

file frequency_manager.hpp

#include “real_time_tools/timer.hpp”

Tools for enforcing a desired frequency in a loop.

Author: Vincent Berenz (vberenz@tue.mpg.de) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2020-03-22

file iostream.hpp

#include <boost/filesystem.hpp>

Tools for console message display.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

file mutex.hpp

#include <string>

#include <condition_variable>

#include <mutex>

This file implements a real time safe mutex with the dedicated libraries. The API tries to fit the std API as much as possible.

Author: Maximilien Naveau license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-11-19

Defines

rt_printf

file process_manager.hpp

#include <vector>

Tools to fix the CPU to specific processor.

Author: Maximilien Naveau (maximilien.naveau@gmail.com)
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-06

file realtime_check.hpp

#include <math.h>

#include <chrono>

#include <iostream>

#include <limits>

#include <mutex>

Tools for checking the real time of an algorithm.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

file rt_mutex.hpp

#include <pthread.h>

#include <sys/time.h>

Expose real time OSs mutex through a common API.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

Typedefs

typedef pthread_mutex_t rt_mutex: Alias for the real time mutex.

typedef pthread_cond_t rt_cond: Alias for the real time condition variable.

Functions

static inline int rt_mutex_init(rt_mutex *mutex): Initialize the mutex.

static inline int rt_mutex_destroy(rt_mutex *mutex): Destroy the mutex.

static inline int rt_mutex_lock(rt_mutex *mutex): Lock the mutex.

static inline int rt_mutex_unlock(rt_mutex *mutex): Unlock the mutex.

file spinner.hpp

#include <unistd.h>

#include <chrono>

Tools for maintaining the timing on a while loop.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

file thread.hpp

#include <functional>

#include <memory>

#include <string>

#include <vector>

Author: Maximilien Naveau (mnaveau@tue.mpg.de) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-11-21

file threadsafe_object.hpp

#include <array>

#include <map>

#include <memory>

#include <tuple>

#include <vector>

#include “real_time_tools/timer.hpp”

#include <condition_variable>

#include <mutex>

#include “real_time_tools/threadsafe/threadsafe_object.hxx”

This file declares templated container for data buffering.

Author: Manuel Wuthrich (manuel.wuthrich@gmail.com)
Author: Maximilien Naveau (maximilien.naveau@gmail.com)
Version: 0.1
Date: 2018-11-27

file threadsafe_object.hxx

#include “real_time_tools/timer.hpp”

This file defines the functions from threadsafe_object.hpp.

Author: Manuel Wuthrich (manuel.wuthrich@gmail.com)
Author: Maximilien Naveau (maximilien.naveau@gmail.com)
Version: 0.1
Date: 2018-11-29

file timer.hpp

#include <unistd.h>

#include <chrono>

#include <cmath>

#include <deque>

#include <string>

#include “real_time_tools/iostream.hpp”

Some tools to measure (ellapsed) time.

Author: Maximilien Naveau (maximilien.naveau@gmail.com) license License BSD-3-Clause
Copyright: Copyright (c) 2019, New York University and Max Planck Gesellschaft.
Date: 2019-05-22

file usb_stream.hpp: #include <array>

#include <iomanip>

#include <iostream>

#include <sstream>

#include <string>

#include <vector>

#include <stdint.h>

file real_time_tools.cpp

#include “real_time_tools/frequency_manager.hpp”

#include <pybind11/pybind11.h>

#include <pybind11/stl.h>

Functions

PYBIND11_MODULE(real_time_tools_cpp_bindings, m)

page todo

Member real_time_tools::RealTimeThreadParameters::delay_ns_: Unknow Xenomai parameter

Member real_time_tools::SingletypeThreadsafeObject< Type, SIZE >::set (Type datum): ”This is used for backward comaptibility.”, Manuel Which bakward?

Member real_time_tools::ThreadsafeHistoryInterface< Type >::add ()=0: Manuel, could you delete this class or provide an implementation?

page license

File checkpoint_timer.hpp: BSD 3-clause

File checkpoint_timer.hxx

BSD 3-clause

File demo_checkpoint_timer.cpp: BSD 3-clause

dir demos

dir include

dir include/real_time_tools

dir srcpy

dir include/real_time_tools/threadsafe

example demo_checkpoint_timer.cpp

Demo on how to use the CheckpointTimer.Note that when the statistics are printed like this, the printing is included in the time measurement of the total loop duration.

#include <real_time_tools/checkpoint_timer.hpp>
#include <real_time_tools/timer.hpp>

void init()
{
    real_time_tools::Timer::sleep_ms(3);
}
void do_some_stuff()
{
    real_time_tools::Timer::sleep_ms(20);
}
void write_log()
{
    real_time_tools::Timer::sleep_ms(6);
}

int main()
{

    // set second template argument to false to disable timer
    real_time_tools::CheckpointTimer<3, true> timer;

    for (int i = 0; i < 1000; i++)
    {
        timer.start();

        init();
        timer.checkpoint("initialize");

        do_some_stuff();
        timer.checkpoint("do some stuff");

        write_log();
        timer.checkpoint("logging");

        // print the timing results every 100 iterations
        if (i % 100 == 0 && i > 0)
        {
            timer.print_statistics();
        }
    }

    return 0;
}

example demo_realtime_check.cpp

This demos has for purpose to present the class real_time_tools::RealTimeCheck. This class measures the frequency of a loop and compares it with a threshold frequency. As demonstrated below, the class takes as input the desired frequency and the threshold frequency.

In order to enable the measurement of the your loop one need to call the real_time_tools::RealTimeCheck::tick() function.

Finally the statistical results can be displayed via the real_time_tools::RealTimeCheck::print() methods.

#include "real_time_tools/realtime_check.hpp"
#include "real_time_tools/thread.hpp"
#include "real_time_tools/timer.hpp"

THREAD_FUNCTION_RETURN_TYPE thread_function(void*)
{
    double freq = 1000.0;  // 1kz
    double switch_freq = 990;
    real_time_tools::RealTimeCheck rc(freq, switch_freq);
    int nb_iteration = 10000;
    int a = 0;

    printf("sleeping time is %f seconds", 1.0 / freq);

    for (int i = 0; i < nb_iteration; ++i)
    {
        rc.tick();
        a++;
        real_time_tools::Timer::sleep_sec(1.0 /
                                          freq);  // microseconds, so in Ghz
    }

    printf("\n");
    rc.print();
    printf("\n");

    return THREAD_FUNCTION_RETURN_VALUE;
}

int main(int, char* [])
{
    real_time_tools::RealTimeThread thread;
    thread.create_realtime_thread(thread_function);
    thread.join();
}

example demo_realtime_strict_check.cpp

This demos has for purpose to present the class real_time_tools::RealTimeCheck. This class measures the frequency of a loop and compares it with a threshold frequency. As demonstrated below, the class takes as input the desired frequency and the threshold frequency.

In order to enable the measurement of the your loop one need to call the real_time_tools::RealTimeCheck::tick() function.

Finally the statistical results can be displayed via the real_time_tools::RealTimeCheck::print() methods.

The difference with the demo_realtime_check.cpp is that we measure the sleeping time as well.

#include "real_time_tools/realtime_check.hpp"
#include "real_time_tools/thread.hpp"

typedef std::chrono::high_resolution_clock my_clock;

THREAD_FUNCTION_RETURN_TYPE thread_function(void*)
{
    double freq = 1000.0;  // 1kz
    double switch_freq = 990;
    int nb_iteration = 1000;

    unsigned period =
        static_cast<unsigned>(round((1.0 / freq) * pow(10.0, 9.0)));
    my_clock::duration clock_period(period);
    real_time_tools::RealTimeCheck rc(freq, switch_freq);
    int a = 0;
    my_clock::time_point start, stop, mid;
    my_clock::duration sleep_duration_diff;
    struct timespec sleep_duration, out_sleep;

    printf("reference period is %ld\n", clock_period.count());

    for (int i = 0; i < nb_iteration; ++i)
    {
        start = my_clock::now();

        rc.tick();

        a++;
        // printf("%d %d", sleep_duration.tv_nsec, out_sleep.tv_nsec);
        // printf("%ld ; %ld ; ", sleep_duration.tv_nsec,
        // sleep_duration_diff.count()); printf("sleeping time is %ld  \n",
        // sleep_duration.tv_nsec);

        mid = my_clock::now();
        sleep_duration.tv_nsec =
            (clock_period - sleep_duration_diff - (mid - start)).count();

        nanosleep(&sleep_duration, &out_sleep);  // microseconds, so in Ghz

        stop = my_clock::now();
        sleep_duration_diff = my_clock::duration(
            (unsigned)((stop - mid) -
                       my_clock::duration(sleep_duration.tv_nsec))
                .count());
    }

    printf("\n");
    rc.print();
    printf("\n");

    return THREAD_FUNCTION_RETURN_VALUE;
}

int main(int, char* [])
{
    real_time_tools::RealTimeThread thread;
    thread.create_realtime_thread(thread_function);
    thread.join();
}

example demo_spinner.cpp

This demos has for purpose to present the class real_time_tools::Spinner.This class allows you to time a loop with a simple API.

One need to create a spinner and set the current spinning frequency. Two method are available for this: real_time_tools::Spinner::set_frequency() or real_time_tools::Spinner::set_period()..

Once this is set one just needs to call real_time_tools::Spinner::spin() and the thread will sleep just the amount of time needed in order for the loop to cadenced properly.

#include "real_time_tools/realtime_check.hpp"
#include "real_time_tools/spinner.hpp"
#include "real_time_tools/thread.hpp"

THREAD_FUNCTION_RETURN_TYPE thread_function(void*)
{
    double frequency = 300.0;
    double switch_frequency = 290;

    real_time_tools::RealTimeCheck realtime_check(frequency, switch_frequency);
    real_time_tools::Spinner spinner;
    spinner.set_frequency(frequency);

    for (int i = 0; i < 500; i++)
    {
        realtime_check.tick();
        spinner.spin();
    }

    std::cout << "\n";
    realtime_check.print();
    std::cout << "\n";

    return THREAD_FUNCTION_RETURN_VALUE;
}

int main(int, char* [])
{
    real_time_tools::RealTimeThread thread;
    thread.create_realtime_thread(thread_function);
    thread.join();
}

example demo_timing.cpp

This demos has for purpose to present the class real_time_tools::Timer.This class allows you to use the real time clocks. And measure durations and extract statistics on them.

Inn this example we create a simple loop cadence by the real_time_tools::Spinner. And we measure the period of the loop.

In order to do so one need to create a real_time_tools::Timer and call the real_time_tools::Timer::tac_tic() method which compute the duration between each call of this method.

The demo displays the statistics of the measured time every milliseconds.

#include "real_time_tools/realtime_check.hpp"
#include "real_time_tools/spinner.hpp"
#include "real_time_tools/thread.hpp"
#include "real_time_tools/timer.hpp"

THREAD_FUNCTION_RETURN_TYPE thread_function(void*)
{
    double frequency = 1000;

    real_time_tools::Spinner spinner;
    spinner.set_frequency(frequency);

    real_time_tools::Timer timer;

    while (true)
    {
        for (int i = 0; i < frequency; i++)
        {
            spinner.spin();
            timer.tac_tic();
        }

        timer.print_statistics();
    }

    return THREAD_FUNCTION_RETURN_VALUE;
}

int main(int, char* [])
{
    real_time_tools::RealTimeThread thread;
    thread.create_realtime_thread(thread_function);
    thread.join();
}

example demo_usb_stream_imu_3DM_GX3_25.cpp

In order to use this Demo one must have an IMU 3DM-GX3-25 from micro-strain plug in one of the usb port of the computer.https://atlas.is.localnet/confluence/display/AMDW/Microstrain+3DM+IMUs?preview=/8979810/17761244/3DM-GX3-Data-Communications-Protocol.pdf

This demos present the use of the usb socket use using the real_time_tools API.

One need to create a real_time_tools::UsbStream. This class allows you to open a device, which means that the class connects this process to a usb communication socket.One can initialize the socket parameters through the real_time_tools::PortConfig structure. Once open one can simply use the communication protocole of the hardware to send and receive messages.

#include "real_time_tools/timer.hpp"
#include "real_time_tools/usb_stream.hpp"

void continuous_mode_on(real_time_tools::UsbStream& usb_stream,
                        bool stream_mode)
{
    std::vector<uint8_t> reply;
    std::vector<uint8_t> command;

    command.resize(4);
    command[0] = 0xc4;  // set continuous mode on
    command[1] = 0xc1;  // user confirmation 1
    command[2] = 0x29;  // user confirmation 2
    command[3] =
        0xc2;  // Acceleration and angular rate continuously broadcasted
    reply.resize(8, 0);  // answer in 8 bits.

    rt_printf("The IMU will blink fast\n");
    while (!(reply[0] == 0xC4 && reply[1] == 0xc2))
    {
        usb_stream.write_device(command);
        usb_stream.read_device(reply, stream_mode);
    }
    rt_printf("Device answer is: %s\n",
              real_time_tools::UsbStream::msg_debug_string(reply).c_str());
    rt_printf("The IMU should blink fast\n");
}

bool is_continuous_mode_on(real_time_tools::UsbStream& usb_stream,
                           bool stream_mode)
{
    std::vector<uint8_t> reply;
    std::vector<uint8_t> command;

    command.resize(4);
    command[0] = 0xd4;   // set continuous mode on
    command[1] = 0xa3;   // user confirmation 1
    command[2] = 0x47;   // user confirmation 2
    command[3] = 0;      // request continuous mode
    reply.resize(4, 0);  // answer in 8 bits.

    bool success = usb_stream.write_device(command);
    success = success && usb_stream.read_device(reply, stream_mode);
    rt_printf("is continuous mode reply: %s\n",
              real_time_tools::UsbStream::msg_debug_string(reply).c_str());
    return success && (reply[1] > 0);
}

void continuous_mode_off(real_time_tools::UsbStream& usb_stream,
                         bool stream_mode)
{
    std::vector<uint8_t> reply;
    std::vector<uint8_t> command;

    command.resize(4);
    command[0] = 0xc4;  // set continuous mode on
    command[1] = 0xc1;  // user confirmation 1
    command[2] = 0x29;  // user confirmation 2
    command[3] =
        0x00;  // Acceleration and angular rate continuously broadcasted
    reply.resize(8, 0xFF);  // answer in 8 bits.

    rt_printf("The IMU will blink slowly\n");
    while (!(reply[0] == 0xC4 && reply[1] == 0x00))
    {
        usb_stream.write_device(command);
        usb_stream.read_device(reply, stream_mode);
    }
    rt_printf("Device answer is: %s\n",
              real_time_tools::UsbStream::msg_debug_string(reply).c_str());
    rt_printf("The IMU should blink slowly\n");
}

void reset(real_time_tools::UsbStream& usb_stream, bool stream_mode)
{
    std::vector<uint8_t> reply;
    std::vector<uint8_t> command;

    command.resize(3);
    command[0] = 0xfe;   // reset device
    command[1] = 0x9e;   // user confirmation 1
    command[2] = 0x3a;   // user confirmation 2
    reply.resize(0, 0);  // answer in 8 bits.

    rt_printf("The IMU is resetting\n");
    usb_stream.write_device(command);
    usb_stream.read_device(reply, stream_mode);
    rt_printf("Device answer is: %s\n",
              real_time_tools::UsbStream::msg_debug_string(reply).c_str());
    rt_printf("The IMU is reset\n");
    real_time_tools::Timer::sleep_sec(10);
}

int main(int argc, char** argv)
{
    if (argc != 2)
    {
        printf("usage: demo_device_stream <device>\ne.g. %s /dev/tty0\n",
               argv[0]);
        return -1;
    }

    // Let us acquire the device path from the application arguments
    std::string device = std::string(argv[1]);

    real_time_tools::UsbStream usb_stream;

    if (!usb_stream.open_device(device))
    {
        return -1;
    }

    real_time_tools::PortConfig port_config;
    port_config.rts_cts_enabled_ = false;
    port_config.parity_ = false;
    port_config.stop_bits_ = real_time_tools::PortConfig::StopBits::one;
    port_config.prepare_size_definition_ = false;
    port_config.data_bits_ = real_time_tools::PortConfig::cs8;
    port_config.baude_rate_ = 115200;
    usb_stream.set_port_config(port_config);
    usb_stream.set_poll_mode_timeout(0.1);

    // stream mode of the usb port
    bool stream_mode = false;

    real_time_tools::Timer::sleep_sec(1);

    continuous_mode_on(usb_stream, stream_mode);
    real_time_tools::Timer::sleep_sec(5);

    usb_stream.flush();
    continuous_mode_off(usb_stream, stream_mode);
    usb_stream.flush();

    rt_printf("Close port\n");
    usb_stream.close_device();

    rt_printf("Stop program\n");
    return 0;
}