artdaq_core  v3_05_07
artdaq::SharedMemoryManager Class Reference

The SharedMemoryManager creates a Shared Memory area which is divided into a number of fixed-size buffers. It provides for multiple readers and multiple writers through a dual semaphore system. More...

#include <artdaq-core/Core/SharedMemoryManager.hh>

Inheritance diagram for artdaq::SharedMemoryManager:
artdaq::SharedMemoryFragmentManager

Public Types

enum  BufferSemaphoreFlags { BufferSemaphoreFlags::Empty, BufferSemaphoreFlags::Writing, BufferSemaphoreFlags::Full, BufferSemaphoreFlags::Reading }
 The BufferSemaphoreFlags enumeration represents the different possible "states" of a given shared memory buffer. More...
 

Public Member Functions

 SharedMemoryManager (uint32_t shm_key, size_t buffer_count=0, size_t buffer_size=0, uint64_t buffer_timeout_us=100 *1000000, bool destructive_read_mode=true)
 SharedMemoryManager Constructor. More...
 
virtual ~SharedMemoryManager () noexcept
 SharedMemoryManager Destructor.
 
bool Attach (size_t timeout_usec=0)
 Reconnect to the shared memory segment.
 
int GetBufferForReading ()
 Finds a buffer that is ready to be read, and reserves it for the calling manager. More...
 
int GetBufferForWriting (bool overwrite)
 Finds a buffer that is ready to be written to, and reserves it for the calling manager. More...
 
bool ReadyForRead ()
 Whether any buffer is ready for read. More...
 
virtual bool ReadyForWrite (bool overwrite)
 Whether any buffer is available for write. More...
 
size_t ReadReadyCount ()
 Count the number of buffers that are ready for reading. More...
 
size_t WriteReadyCount (bool overwrite)
 Count the number of buffers that are ready for writing. More...
 
std::deque< int > GetBuffersOwnedByManager (bool locked=true)
 Get the list of all buffers currently owned by this manager instance. More...
 
size_t BufferDataSize (int buffer)
 Get the current size of the buffer's data. More...
 
size_t BufferSize ()
 Get the size of of a single buffer.
 
void ResetReadPos (int buffer)
 Set the read position of the given buffer to the beginning of the buffer. More...
 
void ResetWritePos (int buffer)
 Set the write position of the given buffer to the beginning of the buffer. More...
 
void IncrementReadPos (int buffer, size_t read)
 Increment the read position for a given buffer. More...
 
bool IncrementWritePos (int buffer, size_t written)
 Increment the write position for a given buffer. More...
 
bool MoreDataInBuffer (int buffer)
 Determine if more data is available to be read, based on the read position and data size. More...
 
bool CheckBuffer (int buffer, BufferSemaphoreFlags flags)
 Check both semaphore conditions (Mode flag and manager ID) for a given buffer. More...
 
void MarkBufferFull (int buffer, int destination=-1)
 Release a buffer from a writer, marking it Full and ready for a reader. More...
 
void MarkBufferEmpty (int buffer, bool force=false)
 Release a buffer from a reader, marking it Empty and ready to accept more data. More...
 
bool ResetBuffer (int buffer)
 Resets the buffer from Reading to Full. This operation will only have an effect if performed by the owning manager or if the buffer has timed out. More...
 
void GetNewId ()
 Assign a new ID to the current SharedMemoryManager, if one has not yet been assigned.
 
uint16_t GetAttachedCount () const
 Get the number of attached SharedMemoryManagers. More...
 
void ResetAttachedCount () const
 Reset the attached manager count to 0.
 
int GetMyId () const
 Get the ID number of the current SharedMemoryManager. More...
 
int GetRank () const
 Get the rank of the owner of the Shared Memory (artdaq assigns rank to each artdaq process for data flow) More...
 
void SetRank (int rank)
 Set the rank stored in the Shared Memory, if the current instance is the owner of the shared memory. More...
 
bool IsValid () const
 Is the shared memory pointer valid? More...
 
bool IsEndOfData () const
 Determine whether the Shared Memory is marked for destruction (End of Data)
 
size_t size () const
 Get the number of buffers in the shared memory segment. More...
 
size_t Write (int buffer, void *data, size_t size)
 Write size bytes of data from the given pointer to a buffer. More...
 
bool Read (int buffer, void *data, size_t size)
 Read size bytes of data from buffer into the given pointer. More...
 
virtual std::string toString ()
 Write information about the SharedMemory to a string. More...
 
uint32_t GetKey () const
 Get the key of the shared memory attached to this SharedMemoryManager. More...
 
void * GetReadPos (int buffer)
 Get a pointer to the current read position of the buffer. More...
 
void * GetWritePos (int buffer)
 Get a pointer to the current write position of the buffer. More...
 
void * GetBufferStart (int buffer)
 Get a pointer to the start position of the buffer. More...
 
void Detach (bool throwException=false, std::string category="", std::string message="", bool force=false)
 Detach from the Shared Memory segment, optionally throwing a cet::exception with the specified properties. More...
 
uint64_t GetBufferTimeout () const
 Gets the configured timeout for buffers to be declared "stale". More...
 
size_t GetBufferCount () const
 Gets the number of buffers which have been processed through the Shared Memory. More...
 
size_t GetLastSeenBufferID () const
 Gets the highest buffer number either written or read by this SharedMemoryManager. More...
 
size_t GetLowestSeqIDRead () const
 Gets the lowest sequence ID that has been read by any reader, as reported by the readers.
 
void SetMinWriteSize (size_t size)
 Sets the threshold after which a buffer should be considered "non-empty" (in case of default headers) More...
 
std::list< std::pair< int,
BufferSemaphoreFlags > > 
GetBufferReport ()
 Get a report on the status of each buffer. More...
 
void TouchBuffer (int buffer)
 Touch the given buffer (update its last_touch_time)
 

Static Public Member Functions

static std::string FlagToString (BufferSemaphoreFlags flag)
 Convert a BufferSemaphoreFlags variable to its string represenatation. More...
 

Detailed Description

The SharedMemoryManager creates a Shared Memory area which is divided into a number of fixed-size buffers. It provides for multiple readers and multiple writers through a dual semaphore system.

Definition at line 17 of file SharedMemoryManager.hh.

Member Enumeration Documentation

The BufferSemaphoreFlags enumeration represents the different possible "states" of a given shared memory buffer.

Enumerator
Empty 

The buffer is empty, and waiting for a writer.

Writing 

The buffer is currently being written to.

Full 

The buffer is full, and waiting for a reader.

Reading 

The buffer is currently being read from.

Definition at line 23 of file SharedMemoryManager.hh.

Constructor & Destructor Documentation

artdaq::SharedMemoryManager::SharedMemoryManager ( uint32_t  shm_key,
size_t  buffer_count = 0,
size_t  buffer_size = 0,
uint64_t  buffer_timeout_us = 100 * 1000000,
bool  destructive_read_mode = true 
)

SharedMemoryManager Constructor.

Parameters
shm_keyThe key to use when attaching/creating the shared memory segment
buffer_countThe number of buffers in the shared memory
buffer_sizeThe size of each buffer
buffer_timeout_usThe maximum amount of time a buffer can be left untouched by its owner (if 0, buffers do not expire) before being returned to its previous state.
destructive_read_modeWhether a read operation empties the buffer (default: true, false for broadcast mode)

Definition at line 57 of file SharedMemoryManager.cc.

Member Function Documentation

size_t artdaq::SharedMemoryManager::BufferDataSize ( int  buffer)

Get the current size of the buffer's data.

Parameters
bufferBuffer ID of buffer
Returns
Current size of data in the buffer

Definition at line 592 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::CheckBuffer ( int  buffer,
BufferSemaphoreFlags  flags 
)

Check both semaphore conditions (Mode flag and manager ID) for a given buffer.

Parameters
bufferBuffer ID of buffer
flagsExpected Mode flag
Returns
Whether the buffer passed the check

Definition at line 712 of file SharedMemoryManager.cc.

void artdaq::SharedMemoryManager::Detach ( bool  throwException = false,
std::string  category = "",
std::string  message = "",
bool  force = false 
)

Detach from the Shared Memory segment, optionally throwing a cet::exception with the specified properties.

Parameters
throwExceptionWhether to throw an exception after detaching
categoryCategory for the cet::exception
messageMessage for the cet::exception
forceWhether to mark shared memory for destruction even if not owner (i.e. from signal handler)

Definition at line 1051 of file SharedMemoryManager.cc.

static std::string artdaq::SharedMemoryManager::FlagToString ( BufferSemaphoreFlags  flag)
inlinestatic

Convert a BufferSemaphoreFlags variable to its string represenatation.

Parameters
flagBufferSemaphoreFlags variable to convert
Returns
String representation of flag

Definition at line 36 of file SharedMemoryManager.hh.

uint16_t artdaq::SharedMemoryManager::GetAttachedCount ( ) const

Get the number of attached SharedMemoryManagers.

Returns
The number of attached SharedMemoryManagers

Definition at line 860 of file SharedMemoryManager.cc.

size_t artdaq::SharedMemoryManager::GetBufferCount ( ) const
inline

Gets the number of buffers which have been processed through the Shared Memory.

Returns
The number of buffers processed by the Shared Memory

Definition at line 324 of file SharedMemoryManager.hh.

int artdaq::SharedMemoryManager::GetBufferForReading ( )

Finds a buffer that is ready to be read, and reserves it for the calling manager.

Returns
The id number of the buffer. -1 indicates no buffers available for read.

Definition at line 251 of file SharedMemoryManager.cc.

int artdaq::SharedMemoryManager::GetBufferForWriting ( bool  overwrite)

Finds a buffer that is ready to be written to, and reserves it for the calling manager.

Parameters
overwriteWhether to consider buffers that are in the Full and Reading state as ready for write (non-reliable mode)
Returns
The id number of the buffer. -1 indicates no buffers available for write.

Definition at line 343 of file SharedMemoryManager.cc.

std::list< std::pair< int, artdaq::SharedMemoryManager::BufferSemaphoreFlags > > artdaq::SharedMemoryManager::GetBufferReport ( )

Get a report on the status of each buffer.

Returns
A list of manager_id, semaphore pairs

Definition at line 985 of file SharedMemoryManager.cc.

std::deque< int > artdaq::SharedMemoryManager::GetBuffersOwnedByManager ( bool  locked = true)

Get the list of all buffers currently owned by this manager instance.

Parameters
lockedDefault = true, Whether to lock search_mutex_ before checking buffer ownership (skipped in Detach)
Returns
A std::deque<int> of buffer IDs currently owned by this manager instance.

Definition at line 554 of file SharedMemoryManager.cc.

void * artdaq::SharedMemoryManager::GetBufferStart ( int  buffer)

Get a pointer to the start position of the buffer.

Parameters
bufferBuffer ID of buffer
Returns
void* pointer to buffer start position

Definition at line 980 of file SharedMemoryManager.cc.

uint64_t artdaq::SharedMemoryManager::GetBufferTimeout ( ) const
inline

Gets the configured timeout for buffers to be declared "stale".

Returns
The buffer timeout, in microseconds

Definition at line 318 of file SharedMemoryManager.hh.

uint32_t artdaq::SharedMemoryManager::GetKey ( ) const
inline

Get the key of the shared memory attached to this SharedMemoryManager.

Returns
The shared memory key

Definition at line 282 of file SharedMemoryManager.hh.

size_t artdaq::SharedMemoryManager::GetLastSeenBufferID ( ) const
inline

Gets the highest buffer number either written or read by this SharedMemoryManager.

Returns
The highest buffer id written or read by this SharedMemoryManager

Definition at line 330 of file SharedMemoryManager.hh.

int artdaq::SharedMemoryManager::GetMyId ( ) const
inline

Get the ID number of the current SharedMemoryManager.

Returns
The ID number of the current SharedMemoryManager

Definition at line 220 of file SharedMemoryManager.hh.

int artdaq::SharedMemoryManager::GetRank ( ) const
inline

Get the rank of the owner of the Shared Memory (artdaq assigns rank to each artdaq process for data flow)

Returns
The rank of the owner of the Shared Memory

Definition at line 226 of file SharedMemoryManager.hh.

void * artdaq::SharedMemoryManager::GetReadPos ( int  buffer)

Get a pointer to the current read position of the buffer.

Parameters
bufferBuffer ID of buffer
Returns
void* pointer to the buffer's current read position

Definition at line 967 of file SharedMemoryManager.cc.

void * artdaq::SharedMemoryManager::GetWritePos ( int  buffer)

Get a pointer to the current write position of the buffer.

Parameters
bufferBuffer ID of buffer
Returns
void* pointer to buffer's current write position

Definition at line 973 of file SharedMemoryManager.cc.

void artdaq::SharedMemoryManager::IncrementReadPos ( int  buffer,
size_t  read 
)

Increment the read position for a given buffer.

Parameters
bufferBuffer ID of buffer
readNumber of bytes by which to increment read position

Definition at line 650 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::IncrementWritePos ( int  buffer,
size_t  written 
)

Increment the write position for a given buffer.

Parameters
bufferBuffer ID of buffer
writtenNumber of bytes by which to increment write position
Returns
Whether the write is allowed

Definition at line 669 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::IsValid ( ) const
inline

Is the shared memory pointer valid?

Returns
Whether the shared memory pointer is valid

Definition at line 241 of file SharedMemoryManager.hh.

void artdaq::SharedMemoryManager::MarkBufferEmpty ( int  buffer,
bool  force = false 
)

Release a buffer from a reader, marking it Empty and ready to accept more data.

Parameters
bufferBuffer ID of buffer
forceForce buffer to empty state (only if manager_id_ == 0)

Definition at line 744 of file SharedMemoryManager.cc.

void artdaq::SharedMemoryManager::MarkBufferFull ( int  buffer,
int  destination = -1 
)

Release a buffer from a writer, marking it Full and ready for a reader.

Parameters
bufferBuffer ID of buffer
destinationIf desired, a destination manager ID may be specified for a buffer

Definition at line 723 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::MoreDataInBuffer ( int  buffer)

Determine if more data is available to be read, based on the read position and data size.

Parameters
bufferBuffer ID of buffer
Returns
Whether more data is available in the given buffer.

Definition at line 696 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::Read ( int  buffer,
void *  data,
size_t  size 
)

Read size bytes of data from buffer into the given pointer.

Parameters
bufferBuffer ID of buffer
dataDestination pointer for read
sizeSize of read, in bytes
Returns
Whether the read was successful

Definition at line 905 of file SharedMemoryManager.cc.

size_t artdaq::SharedMemoryManager::ReadReadyCount ( )

Count the number of buffers that are ready for reading.

Returns
The number of buffers ready for reading

Definition at line 446 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::ReadyForRead ( )

Whether any buffer is ready for read.

Returns
True if there is a buffer available

Definition at line 494 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::ReadyForWrite ( bool  overwrite)
virtual

Whether any buffer is available for write.

Parameters
overwriteWhether to allow overwriting full buffers
Returns
True if there is a buffer available

Reimplemented in artdaq::SharedMemoryFragmentManager.

Definition at line 524 of file SharedMemoryManager.cc.

bool artdaq::SharedMemoryManager::ResetBuffer ( int  buffer)

Resets the buffer from Reading to Full. This operation will only have an effect if performed by the owning manager or if the buffer has timed out.

Parameters
bufferBuffer ID of buffer
Returns
Whether the buffer has exceeded the maximum age

Definition at line 777 of file SharedMemoryManager.cc.

void artdaq::SharedMemoryManager::ResetReadPos ( int  buffer)

Set the read position of the given buffer to the beginning of the buffer.

Parameters
bufferBuffer ID of buffer

Definition at line 611 of file SharedMemoryManager.cc.

void artdaq::SharedMemoryManager::ResetWritePos ( int  buffer)

Set the write position of the given buffer to the beginning of the buffer.

Parameters
bufferBuffer ID of buffer

Definition at line 630 of file SharedMemoryManager.cc.

void artdaq::SharedMemoryManager::SetMinWriteSize ( size_t  size)
inline

Sets the threshold after which a buffer should be considered "non-empty" (in case of default headers)

Parameters
sizeSize (in bytes) after which a buffer will be considered non-empty

Definition at line 341 of file SharedMemoryManager.hh.

void artdaq::SharedMemoryManager::SetRank ( int  rank)
inline

Set the rank stored in the Shared Memory, if the current instance is the owner of the shared memory.

Parameters
rankRank to set

Definition at line 232 of file SharedMemoryManager.hh.

size_t artdaq::SharedMemoryManager::size ( ) const
inline

Get the number of buffers in the shared memory segment.

Returns
The number of buffers in the shared memory segment

Definition at line 252 of file SharedMemoryManager.hh.

std::string artdaq::SharedMemoryManager::toString ( )
virtual

Write information about the SharedMemory to a string.

Returns
String describing current state of SharedMemory and buffers

Definition at line 935 of file SharedMemoryManager.cc.

size_t artdaq::SharedMemoryManager::Write ( int  buffer,
void *  data,
size_t  size 
)

Write size bytes of data from the given pointer to a buffer.

Parameters
bufferBuffer ID of buffer
dataSource pointer for write
sizeSize of write, in bytes
Returns
Amount of data written, in bytes

Definition at line 875 of file SharedMemoryManager.cc.

size_t artdaq::SharedMemoryManager::WriteReadyCount ( bool  overwrite)

Count the number of buffers that are ready for writing.

Parameters
overwriteWhether to consider buffers that are in the Full and Reading state as ready for write (non-reliable mode)
Returns
The number of buffers ready for writing

Definition at line 471 of file SharedMemoryManager.cc.


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