ShmControl provides the basic data model for the queue and low level operations on the shared memory queue, some of which are atomic. More...

#include <shm.hpp>

Inheritance diagram for ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >:

Classes
struct	Element

struct	Queue

Public Types
using	CounterType = typename ShmControlBase<ShmTraits>::CounterType

using	SharedMemoryObject = typename ShmTraits::SharedMemoryObject

using	value_type = Element

using	size_type = typename NonConstTraits<value_type>::size_type

using	reference = typename NonConstTraits<value_type>::reference

using	const_reference = typename ConstTraits<value_type>::reference

using	difference_type = ptrdiff_t

using	ConstIterator = detail::Iterator<ShmControl, ConstTraits<value_type>>

using	Iterator = detail::Iterator<ShmControl, NonConstTraits<value_type>>

Public Types inherited from ipcq::detail::ShmControlBase< BoostInterprocessTraits >
using	CounterType

using	SharedMemoryObject

using	MappedRegion

Public Member Functions
	ShmControl (char const *name, size_t capacity, std::optional< numapp::MemPolicy > mem_policy=std::nullopt, int mmap_flags=0)
	Create a new (owned) named shared memory segment.

	ShmControl (char const *name)
	Open an existing (not owned) shared memory segment in read only mode.

	~ShmControl () noexcept

	ShmControl (ShmControl &&rhs) noexcept
	Moves from rhs into this.

ShmControl &	operator= (ShmControl &&rhs) noexcept
	Moves from rhs into this.

constexpr void	AtomicLoadState () noexcept
	Load queue state from shared memory.

constexpr void	AtomicStoreState () noexcept
	Store queue range state to shared memory.

void	Signal ()
	Signal objects blocking on AwaitSignal.

template<class Rep, class Period, class Predicate>
bool	AwaitSignal (std::chrono::duration< Rep, Period > timeout, Predicate pred) noexcept
	Await notification signal from writer.

constexpr void	Pop ()
	Pop first element in queue.

constexpr bool	IsFull () const noexcept

constexpr bool	IsEmpty () const noexcept

constexpr bool	IsClosed () const noexcept

constexpr void	Close () noexcept
	Close queue for further writing.

std::error_code	Push (const T &element) noexcept
	Push element to back of queue, if `IsFull()` it will overwrite first element.

std::error_code	Push (const T *data, size_t n) noexcept

reference	operator[] (size_type index)

const_reference	operator[] (size_type index) const

constexpr size_type	Size () const noexcept

constexpr value_type *	GetBuffer () const noexcept

constexpr value_type *	GetQueuePtr () const noexcept

constexpr ConstIterator	Begin () const noexcept

constexpr ConstIterator	End () const noexcept

Public Member Functions inherited from ipcq::detail::ShmControlBase< BoostInterprocessTraits >
	ShmControlBase (char const *name, QueueInfo queue_info, std::optional< numapp::MemPolicy > mem_policy=std::nullopt, int mmap_flags=0)
	Owner constructor.

	ShmControlBase (char const *name)
	Non-owner constructor.

	ShmControlBase (ShmControlBase &&rhs) noexcept

ShmControlBase &	operator= (ShmControlBase &&rhs) noexcept

char const *	TopicName () const noexcept

char const *	ShmObjectName () const

constexpr size_t	Capacity () const noexcept

constexpr uint8_t	FileVersion () const noexcept

constexpr pid_t	OwnerPid () const noexcept

Static Public Member Functions
static std::error_code	RemoveShmObject (char const *shm_object_name) noexcept
	Attempts to remove shared memory object.

Public Attributes
friend	Iterator

friend	ConstIterator

Additional Inherited Members
Protected Attributes inherited from ipcq::detail::ShmControlBase< BoostInterprocessTraits >
std::string	m_topic_name
	Topic name, as provided by user.

QueueInfo	m_queue_info

SharedMemoryObject	m_shm_obj
	Manages the shared memory.

ShmRemover< BoostInterprocessTraits >	m_shmem_remover

MappedRegion	m_control_region
	Mapped segment to the control (mapped as read only for Reader).

MappedRegion	m_queue_region
	Mapped region to the queue (mapped as read only for Reader).

ShmControlBlock *	m_ctl_block

bool	m_is_owner
	Indicates if this object owns the shared memory or not.

Detailed Description

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>
class ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >

ShmControl provides the basic data model for the queue and low level operations on the shared memory queue, some of which are atomic.

The shared data model for the queue includes:

a Range describing the valid range of the data and
the capacity of the circular buffer.

This information can be compressed into a single unsigned long long value which can be atomically read or writen.

The atomic operations are:

‘AtomicLoadState()’
AtomicStoreState()

ShmControl does not encode knowledge of the buffer semantics. It merely provides the shared access patterns to it.

Two mappings are created to the shm segment, one for the control block and one for the queue. It's not really important, but if each region is mapped individually, there's less chance that an accidental overwrite of the queue region affects the control region. It also make offset calculations simpler since the control block is not accounted for.

Writer Protocol

Writers to the queue should adhere to the following protocol to ensure data consistency or detect inconsistent states:

To write one or more elements:

Reserve enough room for elements to be written by calling Pop() once for each element to write.
"Publish" change of queue state by calling AtomicStoreState().
Add elements by calling Push().
"Publish" change of queue again by calling AtomicStoreState().

Reader Protocol

Read current queue state with AtomicLoadState()
Verify that iterator is valid.
Copy.
Read current queue state with AtomicLoadState()
Verify that iterator is still valid.
Verify that copied element has the expected counter value.

Important

boost interprocess uses mmap on linux, and it is possible that write combine is used under unknown circumstances. If write combining is enabled then the strong memory ordering is no longer true.

Implementation Notes

boost::shared_memory_object corresponds to a file handle, opened with open(2). boost::shared_memory_object::truncate corresponds to ftruncate(2).

boost::mapped_region construction corresponds to a call to mmap(2) which in the case of ShmControl also allocate, lock and populate the memory using MAP_LOCKED and MAP_POPULATE.

User control over memory policy for the allocation is made possible because ShmControl in the "writer" is always the one that creates the boost::shared_memory_object and can then make sure that the chosen memory policy is applied when the allocation is performed in mmap(2).

Definition at line 658 of file shm.hpp.

Member Typedef Documentation

◆ const_reference

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::const_reference = typename ConstTraits<value_type>::reference

Definition at line 670 of file shm.hpp.

◆ ConstIterator

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::ConstIterator = detail::Iterator<ShmControl, ConstTraits<value_type>>

Definition at line 672 of file shm.hpp.

◆ CounterType

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::CounterType = typename ShmControlBase<ShmTraits>::CounterType

Definition at line 660 of file shm.hpp.

◆ difference_type

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::difference_type = ptrdiff_t

Definition at line 671 of file shm.hpp.

◆ Iterator

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Iterator = detail::Iterator<ShmControl, NonConstTraits<value_type>>

Definition at line 673 of file shm.hpp.

◆ reference

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::reference = typename NonConstTraits<value_type>::reference

Definition at line 669 of file shm.hpp.

◆ SharedMemoryObject

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::SharedMemoryObject = typename ShmTraits::SharedMemoryObject

Definition at line 661 of file shm.hpp.

◆ size_type

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::size_type = typename NonConstTraits<value_type>::size_type

Definition at line 668 of file shm.hpp.

◆ value_type

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

using ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::value_type = Element

Definition at line 667 of file shm.hpp.

Constructor & Destructor Documentation

◆ ShmControl() [1/3]

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::ShmControl	(	char const *	name,
		size_t	capacity,
		std::optional< numapp::MemPolicy >	mem_policy = std::nullopt,
		int	mmap_flags = 0 )

inlineexplicit

Create a new (owned) named shared memory segment.

Warning: Will (try to) destroy shared memory with same name if it exists.

Parameters

name	Full name of shared memory segment.
capacity	Capacity of queue. Maximum capacity is config::MAX_CAPACITY.
mem_policy	Optional memory policy that is applied when allocating the shared memory.
mmap_flags	Additional flags that will be or-ed with the default flags MAP_LOCKED and MAP_POPULATE.

Exceptions

boost::interprocess::interprocess_exception	if creating shared memory fails.
std::system_error	with Error::Overflow if requested capacity is greater than what can be represented by the queue.

Definition at line 717 of file shm.hpp.

◆ ShmControl() [2/3]

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::ShmControl ( char const * name )

inlineexplicit

Open an existing (not owned) shared memory segment in read only mode.

Parameters

name	Full name of shared memory segment.

Exceptions

std::system_error

If

attaching to shared memory fail
ipcq::Error::TypeMismatch if element or condition policy types don't match
ipcq::Error::Closed if queue is closed or owner does not exist.

Definition at line 777 of file shm.hpp.

◆ ~ShmControl()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::~ShmControl ( )

inlinenoexcept

Definition at line 827 of file shm.hpp.

◆ ShmControl() [3/3]

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::ShmControl ( ShmControl< T, ConditionPolicy, ShmTraits > && rhs )

inlinenoexcept

Moves from rhs into this.

Precondition: rhs is valid.

Postcondition: rhs is invalid.

Definition at line 842 of file shm.hpp.

Member Function Documentation

◆ AtomicLoadState()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

void ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::AtomicLoadState ( )

inlineconstexprnoexcept

Load queue state from shared memory.

Performs acquire-synchronization that pairs with AtomicStoreState.

Definition at line 896 of file shm.hpp.

◆ AtomicStoreState()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

void ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::AtomicStoreState ( )

inlineconstexprnoexcept

Store queue range state to shared memory.

Performs release-synchronization that pairs with AtomicLoadState.

Definition at line 906 of file shm.hpp.

◆ AwaitSignal()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

template<class Rep, class Period, class Predicate>

bool ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::AwaitSignal	(	std::chrono::duration< Rep, Period >	timeout,
		Predicate	pred )

inlinenodiscardnoexcept

Await notification signal from writer.

Returns: false on timeout, true otherwise.

Definition at line 925 of file shm.hpp.

◆ Begin()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

ConstIterator ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Begin ( ) const

inlinenodiscardconstexprnoexcept

Definition at line 1042 of file shm.hpp.

◆ Close()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

void ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Close ( )

inlineconstexprnoexcept

Close queue for further writing.

Existing elements may still be written and Pop() is allowed.

Note: Push() will fail after this.

See also: IsClosed()

Definition at line 969 of file shm.hpp.

◆ End()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

ConstIterator ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::End ( ) const

inlinenodiscardconstexprnoexcept

Definition at line 1046 of file shm.hpp.

◆ GetBuffer()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

value_type * ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::GetBuffer ( ) const

inlinenodiscardconstexprnoexcept

Definition at line 1034 of file shm.hpp.

◆ GetQueuePtr()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

value_type * ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::GetQueuePtr ( ) const

inlinenodiscardconstexprnoexcept

Definition at line 1038 of file shm.hpp.

◆ IsClosed()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

bool ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::IsClosed ( ) const

inlinenodiscardconstexprnoexcept

Returns: true if queue is closed and will not be written to again, false otherwise.

See also: Close().

Definition at line 959 of file shm.hpp.

◆ IsEmpty()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

bool ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::IsEmpty ( ) const

inlinenodiscardconstexprnoexcept

Returns: true if queue is empty, false otherwise.

Definition at line 951 of file shm.hpp.

◆ IsFull()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

bool ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::IsFull ( ) const

inlinenodiscardconstexprnoexcept

Returns: true if queue is full, false otherwise.

Definition at line 944 of file shm.hpp.

◆ operator=()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

ShmControl & ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::operator= ( ShmControl< T, ConditionPolicy, ShmTraits > && rhs )

inlinenoexcept

Moves from rhs into this.

Precondition: rhs is valid.

Postcondition: rhs is invalid.

Definition at line 869 of file shm.hpp.

◆ operator[]() [1/2]

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

reference ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::operator[] ( size_type index )

inlinenodiscard

Definition at line 1020 of file shm.hpp.

◆ operator[]() [2/2]

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

const_reference ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::operator[] ( size_type index ) const

inlinenodiscard

Definition at line 1025 of file shm.hpp.

◆ Pop()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

void ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Pop ( )

inlineconstexpr

Pop first element in queue.

Note: : Changes won't be seen by others until AtomicStoreState is invoked.

Definition at line 934 of file shm.hpp.

◆ Push() [1/2]

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

std::error_code ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Push ( const T & element )

inlinenodiscardnoexcept

Push element to back of queue, if IsFull() it will overwrite first element.

Parameters

element Element to push to queue.

Returns: Error::Closed if queue is closed.; 0 if element was added to queue.

Definition at line 980 of file shm.hpp.

◆ Push() [2/2]

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

std::error_code ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Push	(	const T *	data,
		size_t	n )

inlinenodiscardnoexcept

Returns: Error::Closed if queue is closed.

Definition at line 991 of file shm.hpp.

◆ RemoveShmObject()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

static std::error_code ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::RemoveShmObject ( char const * shm_object_name )

inlinestaticnoexcept

Attempts to remove shared memory object.

Note: shm_object_name is not the topic name, but the raw object name.

Parameters

shm_object_name The raw object name to remove.

Returns: false on error.

Definition at line 692 of file shm.hpp.

◆ Signal()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

void ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Signal ( )

inline

Signal objects blocking on AwaitSignal.

Definition at line 914 of file shm.hpp.

◆ Size()

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

size_type ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Size ( ) const

inlinenodiscardconstexprnoexcept

Definition at line 1030 of file shm.hpp.

Member Data Documentation

◆ ConstIterator

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

friend ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::ConstIterator

Definition at line 676 of file shm.hpp.

◆ Iterator

template<class T, class ConditionPolicy, class ShmTraits = BoostInterprocessTraits>

friend ipcq::detail::ShmControl< T, ConditionPolicy, ShmTraits >::Iterator

Definition at line 675 of file shm.hpp.

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

ipcq/src/include/ipcq/detail/shm.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Writer Protocol

Reader Protocol

Important

Implementation Notes

Member Typedef Documentation

◆ const_reference

◆ ConstIterator

◆ CounterType

◆ difference_type

◆ Iterator

◆ reference

◆ SharedMemoryObject

◆ size_type

◆ value_type

Constructor & Destructor Documentation

◆ ShmControl() [1/3]

◆ ShmControl() [2/3]

◆ ~ShmControl()

◆ ShmControl() [3/3]

Member Function Documentation

◆ AtomicLoadState()

◆ AtomicStoreState()

◆ AwaitSignal()

◆ Begin()

◆ Close()

◆ End()

◆ GetBuffer()

◆ GetQueuePtr()

◆ IsClosed()

◆ IsEmpty()

◆ IsFull()

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ Pop()

◆ Push() [1/2]

◆ Push() [2/2]

◆ RemoveShmObject()

◆ Signal()

◆ Size()

Member Data Documentation

◆ ConstIterator

◆ Iterator