cbeam::container::stable_interprocess_container< T > Class Template Reference

Manages type-safe, interprocess container operations with stable serialization. More...

#include <stable_interprocess_container.hpp>

Inheritance diagram for cbeam::container::stable_interprocess_container< T >:

Collaboration diagram for cbeam::container::stable_interprocess_container< T >:

Public Member Functions
	stable_interprocess_container (const std::string &unique_identifier, std::size_t size)
	Constructs a stable_interprocess_container with a specific size and unique identifier.
	stable_interprocess_container (const stable_interprocess_container &)=delete
stable_interprocess_container &	operator= (const stable_interprocess_container &)=delete
	stable_interprocess_container (stable_interprocess_container &&)=delete
stable_interprocess_container &	operator= (stable_interprocess_container &&)=delete
virtual void	clear ()
	Clears the contents of the container.
virtual bool	empty () const
	Checks if the container is empty.
virtual size_t	size () const
	Retrieves the size of the container.
template<typename Func>
void	foreach (Func func)
	Iterates over the elements of the container and performs an action.
Public Member Functions inherited from cbeam::memory::interprocess_shared_memory
	interprocess_shared_memory (const std::string &unique_identifier, std::size_t size)
	Constructor that initializes the shared memory segment.
virtual	~interprocess_shared_memory () noexcept
void *	data () const
	Retrieves the starting address of the shared memory region.
size_t	capacity () const noexcept
	Returns the size of the shared memory region.
lock_guard	get_lock_guard () const
	Acquires a lock_guard for mutex synchronization.
	interprocess_shared_memory (const interprocess_shared_memory &)=delete
interprocess_shared_memory &	operator= (const interprocess_shared_memory &)=delete
	interprocess_shared_memory (interprocess_shared_memory &&)=delete
interprocess_shared_memory &	operator= (interprocess_shared_memory &&)=delete

Protected Member Functions
T	deserialize () const
	Deserializes the shared memory data into a container object.
void	serialize (const T &container)
	Serializes a container object and stores it in shared memory.

Detailed Description

template<typename T>
class cbeam::container::stable_interprocess_container< T >

Manages type-safe, interprocess container operations with stable serialization.

This template class, inheriting from cbeam::memory::interprocess_shared_memory, is specifically designed to provide a stable and consistent framework for managing shared data structures across various shared libraries, even when compiled with different compilers or versions. The 'stable' aspect of this container relates to its capability for automatic serialization and deserialization, ensuring that the data remains coherent and reliable, regardless of the environment it operates in. This feature is particularly crucial in multi-library environments where binary format inconsistencies are common.

The container is intended as a base class for developing specialized container types, such as cbeam::container::stable_interprocess_map. It facilitates seamless and efficient shared data management in interprocess and multi-library contexts. The class ensures that the size of the shared memory segment remains constant once initialized, preventing any runtime size modifications.

Serialization traits for basic data types are provided by default. For specialized data types, custom serialization traits must be implemented based on cbeam::serialization::traits to handle specific serialization behaviors.

• Stable Serialization/Deserialization: Offers robust serialization mechanisms to maintain data integrity across different compiler binaries, ensuring stable data exchange in interprocess environments.
• Base Class for Specialized Containers: Serves as a foundational class for developing specialized container types that require interprocess communication capabilities.
• Type Safety and Flexibility: As a template class, it allows for type-safe operations on various data types, making it versatile for a range of applications.

Usage

This class is essential for applications involving complex, multi-library interactions where shared data structures need to be managed efficiently and consistently, especially in environments with diverse compiler tools and versions.

Template Parameters

T	The type of elements to be stored in the container. Requires implementation of serialization traits if T is not a basic data type.

Constructor & Destructor Documentation

stable_interprocess_container() [1/3]

template<typename T>

cbeam::container::stable_interprocess_container< T >::stable_interprocess_container ( const std::string & unique_identifier, std::size_t size )

inline

Constructs a stable_interprocess_container with a specific size and unique identifier.

This constructor initializes a container designed for interprocess communication, providing automatic serialization and deserialization to ensure stable operations across different shared library contexts. The term 'stable' refers to the container's ability to maintain data integrity and consistency through these serialization processes. Basic serialization traits for fundamental data types are inherently supported. For specialized data types, additional serialization traits need to be defined, adhering to the structure provided by cbeam::serialization::traits.

The class is intended as a base class for specialized container types, such as cbeam::container::stable_interprocess_map, enabling them to efficiently manage shared data in a multi-library environment. The size of the shared memory segment, once set during construction, remains constant throughout the lifecycle of the container.

Parameters

unique_identifier	A string representing a unique identifier for the shared memory segment. This identifier is essential for distinguishing between different shared memory segments, especially in environments with multiple libraries or processes.
size	The fixed size of the shared memory segment, specified in bytes. This size determines the capacity of the container and cannot be altered after initialization.

stable_interprocess_container() [2/3]

template<typename T>

cbeam::container::stable_interprocess_container< T >::stable_interprocess_container ( const stable_interprocess_container< T > & )

delete

stable_interprocess_container() [3/3]

template<typename T>

cbeam::container::stable_interprocess_container< T >::stable_interprocess_container ( stable_interprocess_container< T > && )

delete

Member Function Documentation

clear()

template<typename T>

virtual void cbeam::container::stable_interprocess_container< T >::clear ( )

inlinevirtual

Clears the contents of the container.

This method clears all the elements in the container, effectively resetting its content to an empty state. The operation is performed in a thread-safe manner using a lock guard to ensure exclusive access during the modification. This is essential in an interprocess or multithreaded environment to maintain data consistency and prevent concurrent access issues.

deserialize()

template<typename T>

T cbeam::container::stable_interprocess_container< T >::deserialize ( ) const

inlineprotected

Deserializes the shared memory data into a container object.

Returns

A deserialized instance of the container.

This protected method deserializes the data stored in the shared memory into a container object of type T. It is used internally by various public methods to safely access and manipulate the container's data. The method ensures that the data integrity is maintained during the deserialization process, which is crucial in an interprocess context.

empty()

template<typename T>

virtual bool cbeam::container::stable_interprocess_container< T >::empty ( ) const

inlinevirtual

Checks if the container is empty.

Returns

A boolean value indicating whether the container is empty.

This method returns true if the container is empty, and false otherwise. The check is performed under a lock guard to ensure thread-safe access to the container's state. This approach is crucial in environments with concurrent access to the container, as it maintains data integrity and consistency.

foreach()

template<typename T>

template<typename Func>

void cbeam::container::stable_interprocess_container< T >::foreach ( Func func )

inline

Iterates over the elements of the container and performs an action.

Parameters

func	A function to be applied to each element in the container.

This method iterates over each element in the container and applies the provided function func to it. The iteration is safely encapsulated within the method, mitigating the need for external synchronization like lock guards. This design choice eliminates the risks associated with exposing begin() and end() iterators, which could lead to inconsistent states if the container's end() changes due to external modifications in a concurrent environment.

Example

stable_interprocess_container<MyType> container("identifier", size);
container.foreach([](const MyType& item) {
    // Perform actions with item
    return true; // Continue iterating
});

operator=() [1/2]

template<typename T>

stable_interprocess_container & cbeam::container::stable_interprocess_container< T >::operator= ( const stable_interprocess_container< T > & )

delete

operator=() [2/2]

template<typename T>

stable_interprocess_container & cbeam::container::stable_interprocess_container< T >::operator= ( stable_interprocess_container< T > && )

delete

serialize()

template<typename T>

void cbeam::container::stable_interprocess_container< T >::serialize ( const T & container )

inlineprotected

Serializes a container object and stores it in shared memory.

Parameters

container

The container object to be serialized.

This protected method serializes the provided container object and stores the serialized data in the shared memory. It ensures that the size of the serialized data does not exceed the capacity of the shared memory. If it does, an exception is thrown. This method is crucial for maintaining the integrity and consistency of the container's data in an interprocess environment.

Exceptions

cbeam::error::runtime_error

if the serialized size exceeds the shared memory capacity.

size()

template<typename T>

virtual size_t cbeam::container::stable_interprocess_container< T >::size ( ) const

inlinevirtual

Retrieves the size of the container.

Returns

The number of elements in the container.

This method returns the number of elements currently held in the container. The operation is carried out under a lock guard to ensure thread-safe access in an interprocess or multithreaded context. This secure approach is essential for maintaining the accuracy and consistency of the size information in a shared environment.

---

The documentation for this class was generated from the following file:

• include/cbeam/container/stable_interprocess_container.hpp