Namespace real_time_tools¶

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.

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(std::string_view 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_view, 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

template<int INDEX> 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”

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.