File shared_memory.hpp

This file declares a class that is used for shared memory segment introspection (e.g. used and free memory)

This file declares some function that encapsulate the use of the shared memory using the boost::interprocess package. usage: see demos and unit tests and documentation.

License:

License BSD-3-Clause

License:

License BSD-3-Clause

Author

Vincent Berenz

Author

Maximilien Naveau (maximilien.naveau@gmail.com)

Copyright

Copyright (c) 2019, New York University and Max Planck Gesellschaft.

Date

2019-05-22

Author

Vincent Berenz

Author

Maximilien Naveau (maximilien.naveau@gmail.com)

Copyright

Copyright (c) 2019, New York University and Max Planck Gesellschaft.

Date

2019-05-22

Defines

SHARED_MEMORY_HPP

DEFAULT_SHARED_MEMORY_SIZE

MAP_STRING_KEY_SEPARATOR

namespace shared_memory

All templated types in this namespaces are elementary types: int, double, float, char*, …

Typedefs

typedef std::map<std::string, std::pair<void*, std::size_t>> ShmObjects

ShmObjects typedef is a simple renaming that ease the for loop writting.

typedef ShmTypeHelper<char>::ElemTypeAllocator ShmCharAllocator

Create a char allocator to ease the creation of strings.

typedef std::basic_string<char, std::char_traits<char>, ShmCharAllocator> ShmString

Create a basic_string type for the Shared Memory.

Functions

void set_segment_sizes(uint multiplier_1025)

sets the size of the segments that will be newly created via the set methods.

Until this function is called, segments are created with a size of 65536 bytes. This function is not interprocess : it will set the size of segments created in the current process

Parameters:

multiplier_1025 – the size of create segment will be multiplier_1025 * 1025 bytes (because memory segment sizes have to be a multiple of 1025)

void set_default_segment_sizes()

set the size of segment newly created to the default size value of 65536

SharedMemorySegment &get_segment(const std::string &segment_id, const bool clear_upon_destruction = false, const bool create = true)

get_segment creates or give back a pointer to a SharedMemorySegment object.

Parameters:

segment_id – is the name of the shared memory segment.

SegmentInfo get_segment_info(const std::string &segment_id)

performs introspection on the segment and return related information.

If the segment does not exists, creates it first.

bool segment_exists(const std::string &segment_id)

returns true if a segment exists under this id

Parameters:

segment_id – is the name of the shared memory segment.

void delete_segment(const std::string &segment_id)

delete_segment deletes the segment of existing shared memory.

it makes sure that all element created in it is destroyed first. (is this needed? I do not know.)

Parameters:

segment_id – is the name of the shared memory segment.

void delete_all_segments()

delete_all_segment delete all mapping to the shared memory used during the current process

void delete_all_segment()

alias for delete_all_segments (for retro compatibility)

template<typename ElemType>
bool delete_object(const std::string &segment_id, const std::string &object_id)

delete_object deletes a particular object in the shared memory segment

Parameters:

segment_id – [in] is the name of the shared memory segment.

Returns:

true if everything went fine.

boost::interprocess::interprocess_mutex &get_segment_mutex(const std::string segment_id)

get_sgement_mutex aquiere a reference to the semgent global mutex.

Parameters:

segment_id – [in] is the name of the shared memory segment.

Returns:

a reference to a boost mutex

void clear_shared_memory(const std::string &segment_id)

clear_shared_memory_segment destroys the shared memory

Parameters:

segment_id – [in] is the name of the shared memory segment.

template<typename ElemType>
void set(const std::string &segment_id, const std::string &object_id, const ElemType &set_)

set instanciates or get pointer to any elementary types in the shared memory.

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

template<typename ElemType>
void set(const std::string &segment_id, const std::string &object_id, const ElemType *set_, const std::size_t size)

set instanciates or get pointer to a fixed sized array of the templated type “T” in the shared memory.

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the pointer to the array of objects to set in the memory.

• size – [in] is the array size.

void set(const std::string &segment_id, const std::string &object_id, const std::string &set_)

set instanciates or get pointer to a string in the shared memory.

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

template<typename ElemType>
void set(const std::string &segment_id, const std::string &object_id, const std::vector<ElemType> &set_)

set instanciates or get pointer to a std::vector<ElemType> in the shared memory.

This will translated as a fixed sized array in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

template<typename ElemType>
void set(const std::string &segment_id, const std::string &object_id, const Eigen::Matrix<ElemType, Eigen::Dynamic, 1> &set_)

set instanciates or get pointer to a Eigen::Matrix<ElemType, Eigen::Dynamic, 1> in the shared memory.

This will translated as a fixed sized array in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

template<typename FirstType, typename SecondType>
void set(const std::string &segment_id, const std::string &object_id, const std::pair<FirstType, SecondType> &set_)

set instanciates or get pointer to a std::pair<FirstType, SecondType> in the shared memory.

This is very usefull to dump maps in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

template<typename KeyType, typename ValueType>
void set(const std::string &segment_id, const std::string &object_id, const std::map<KeyType, ValueType> &set_)

set instanciates or get pointer to a std::vector<ElemType> or an Eigen::Matrix<ElemType, any, any> in the shared memory.

This will translated as a fixed sized array in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

template<typename ElemType>
void get(const std::string &segment_id, const std::string &object_id, ElemType &get_, bool create = true)

get gets a pointer to any elementary types in the shared memory.

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• get_ – [in] is the string to be created in the shared memory

template<typename ElemType>
void get(const std::string &segment_id, const std::string &object_id, ElemType *get_, const std::size_t expected_size, bool create = true)

get gets a pointer to a fixed sized array of the templated type “T” in the shared memory.

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• get_ – [in] is the pointer to the array of objects to set in the memory.

• size – [in] is the array size.

• create – [in] : if false, raise a Non_existing_segment_exception if the segment does not already exist

void get(const std::string &segment_id, const std::string &object_id, std::string &get_, bool create = true)

get gets a pointer to a string in the shared memory.

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• get_ – [in] is the string to be created in the shared memory

• create – [in] : if false, raise a Non_existing_segment_exception if the segment does not already exist

template<typename ElemType>
void get(const std::string &segment_id, const std::string &object_id, std::vector<ElemType> &get_, bool create = true)

get gets a pointer to a std::vector<ElemType> in the shared memory.

This will translated as a fixed sized array in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

• create – [in] : if false, raise a Non_existing_segment_exception if the segment does not already exist

template<typename ElemType>
void get(const std::string &segment_id, const std::string &object_id, Eigen::Matrix<ElemType, Eigen::Dynamic, 1> &get_, bool create = true)

get gets a pointer to a Eigen::Matrix<ElemType, Eigen::Dynamic, 1> in the shared memory.

This will translated as a fixed sized array in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• set_ – [in] is the string to be created in the shared memory

• create – [in] : if false, raise a Non_existing_segment_exception if the segment does not already exist

template<typename FirstType, typename SecondType>
void get(const std::string &segment_id, const std::string &object_id, std::pair<FirstType, SecondType> &get_, bool create = true)

get instanciates or get pointer to a std::pair<FirstType, SecondType> in the shared memory.

This is very usefull to dump maps in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• get_ – [in] is the string to be created in the shared memory

• create – [in] : if false, raise a Non_existing_segment_exception if the segment does not already exist

template<typename KeyType, typename ValueType>
void get(const std::string &segment_id, const std::string &object_id, std::map<KeyType, ValueType> &get_, bool create = true)

get gets a pointer to a std::vector<ElemType> or an Eigen::Matrix<ElemType, any, any> in the shared memory.

This will translated as a fixed sized array in the shared memory

All set functions make sure that the pointer is uniquely created to avoid useless computation time consumption.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• get_ – [in] is the string to be created in the shared memory

• create – [in] : if false, raise a Non_existing_segment_exception if the segment does not already exist

template<class Serializable>
void serialize(const std::string &segment, const std::string &object, const Serializable &serializable)

Serialize the instance into a string which is written in the shared memory.

This uses cereal for serialization, and Serializable must implement a serialize function, see: https://uscilab.github.io/cereal/

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• serializable – [in] is the instance to serialize

template<class Serializable>
void deserialize(const std::string &segment, const std::string &object, Serializable &serializable)

Read from the memory a string that is deserialized into the passed instance of Serializable.

This assumes the serialization and writting in the shared memory has been performed using the serialize function.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• object_id – [in] is the name of the shared memory object to set.

• serializable – [in] is the instance in which the string will be deserialized

void set_verbose(bool mode)

if verbose mode set to true (starting default is false), informaton about newly created objects will be displayed in the terminal.

Call to this function will change the verbose mode only for the current process.

bool wait_for_segment(const std::string &segment_id, int timeout_ms = -1)

wait until the segment is created either via call to a get or set function.

Parameters:

• segment_id – [in] is the name of the shared memory segment.

• timeout_ms – [in] is a timeout in ms

Returns:

true if the segment has been created before the timeout expired, false otherwise.

class SharedMemorySegment

#include <shared_memory.hpp>

The SharedMemorySegment contains the pointers of the shared objects in on shared memrory segment.

We use unamed mutext (interprocess_mutex) and unamed condition variables (interprocess_condition) to be able to instanciate them with classic pointers

Public Functions

SharedMemorySegment(std::string segment_id, bool clear_upon_destruction, bool create)

SharedMemorySegment constructor.

inline ~SharedMemorySegment()

SharedMemorySegment destructor.

void clear_memory()

clear_memory free the shared memory

template<typename ElemType>
void get_object(const std::string &object_id, std::pair<ElemType*, std::size_t> &get_)

get_object registers the object in the current struc and in the shared memory once only.

And returns the pointer to the object and its size. The size will be 1 for simple type and could greater to one for arrays.

Parameters:

object_id – [in] the name of the object in the shared memory.

Param :

void get_object(const std::string &object_id, std::string &get_)

get_object registers the object in the current struc and in the shared memory once only.

And returns the pointer to the object and its size. The size will be 1 for simple type and could greater to one for arrays.

Parameters:

object_id – [in] the name of the object in the shared memory.

Param :

template<typename ElemType>
void set_object(const std::string &object_id, const std::pair<const ElemType*, std::size_t> &set_)

set_object registers the object in the current struc and in the shared memory once only.

And returns the pointer to the object and its size. The size will be 1 for simple type and could greater to one for arrays.

Parameters:

• object_id – [in] the name of the object in the shared memory.

• set_ – [in] the reference to the fetched object.

template<typename ElemType>
bool register_object(const std::string &object_id, const std::pair<ElemType*, std::size_t> &obj_)

register_object registers the object in the segment uniquely.

Parameters:

• object_id – is the name of the object to register.

• obj_ – is the object to be registered.

Returns:

true of a new object has been registered

template<typename ElemType>
bool register_object_read_only(const std::string &object_id)

register_object_read_only registers the object in the segment uniquely.

Parameters:

• object_id – is the name of the object to register

• obj_ – is the object to be registered

Returns:

true of a new object has been registered

template<typename ElemType>
void delete_object(const std::string &object_id)

delete_object delete and object from the shared memory.

Parameters:

object_id – [in] the name of the object in the shared memory.

inline void create_mutex()

create_mutex small factory that allow to make sure that the mutex is created.

inline void destroy_mutex()

destroy_mutex small destructor of the mutext to make sure that it is unlock at critical time.

inline bool is_object_registered(const std::string &object_id)

is_object_registered used to check if the object has been registered or not.

Parameters:

object_id – [in] the name of the object in the shared memory.

Returns:

true if it has been registered

inline void set_clear_upon_destruction(const bool clear_upon_destruction)

set_clear_upon_destruction is a standard setter

Parameters:

clear_upon_destruction – [in] is the value to set

inline const std::string &get_segment_id()

get_segment_id is a standard getter

Returns:

the segment name

inline SegmentInfo get_info()

performs introspection on the segment and return related information

Public Members

boost::interprocess::interprocess_mutex *mutex_

mutex_ this mutex secure ALL the shared memory.

Private Members

boost::interprocess::managed_shared_memory segment_manager_

shm_segment is the boost object that manages the shared memory segment

ShmObjects objects_

objects_ are all the data stored in the segment.

WARNING here we use void* so the use of the set and get functions is the RESPONSABILITY of the user.

The user is to use the SAME type when calling set and get using the shared memory

std::string segment_id_

segment_id_ is the name of the segment inside the shared memory

bool clear_upon_destruction_

clear_upon_destruction_ flag decides if the segment should be cleared upon destruction.

Usage: typically only one process should set this flag to true.

int ravioli_

template<typename ElemType>
struct ShmTypeHelper

#include <shared_memory.hpp>

ShmTypeHelper is a small struct that allow the definition of templated typedef.

Public Types

typedef boost::interprocess::allocator<ElemType, boost::interprocess::managed_shared_memory::segment_manager> ElemTypeAllocator

ShmemAllocator typedef allows to create std::allocator with the boost interprocess library.

typedef boost::container::deque<ElemType, ShmTypeHelper<ElemType>::ElemTypeAllocator> ShmDeque

typedef boost::container::vector<ElemType, ShmTypeHelper<ElemType>::ElemTypeAllocator> ShmVector