fawkes::SharedMemory Class Reference
[Interprocess Communication (IPC)]

Shared memory segment. More...

#include <utils/ipc/shm.h>

Inheritance diagram for fawkes::SharedMemory:

[legend]
List of all members.

Public Member Functions

 SharedMemory (const char *magic_token, SharedMemoryHeader *header, bool is_read_only, bool create, bool destroy_on_delete)
 Create a new shared memory segment.
 SharedMemory (const SharedMemory &s)
 Copy constructor.
virtual ~SharedMemory ()
 Destructor.
bool is_read_only ()
 Check for read-only mode.
bool is_destroyed ()
 Check if segment has been destroyed This can be used if the segment has been destroyed.
bool is_swapable ()
 Check if memory can be swapped out.
bool is_valid ()
 Check validity of shared memory segment.
bool is_creator ()
 Determine if the shared memory segment has been created by this instance.
bool is_protected ()
 Check if memory segment is protected.
void * memptr ()
 Get a pointer to the shared memory This method returns a pointer to the data-segment of the shared memory segment.
size_t data_size ()
 Get the size of the data-segment.
void set (void *memptr)
 Copies data from the memptr to shared memory.
void set_destroy_on_delete (bool destroy)
 Set deletion behaviour.
void add_semaphore ()
 Add semaphore to shared memory segment.
void set_swapable (bool swapable)
 Set shared memory swapable.
void lock_for_read ()
 Lock shared memory segment for reading.
bool try_lock_for_read ()
 Try to aquire lock on shared memory segment for reading.
void lock_for_write ()
 Lock shared memory segment for writing.
bool try_lock_for_write ()
 Try to aquire lock on shared memory segment for writing.
void unlock ()
 Unlock memory.
void * ptr (void *addr)
 Get the real pointer to the data based on an address.
void * addr (void *ptr)
 Get an address from a real pointer.

Static Public Member Functions

static void list (const char *magic_token, SharedMemoryHeader *header, SharedMemoryLister *lister)
 List shared memory segments of a given type.
static void erase (const char *magic_token, SharedMemoryHeader *header, SharedMemoryLister *lister=0)
 Erase shared memory segments of a given type.
static void erase_orphaned (const char *magic_token, SharedMemoryHeader *header, SharedMemoryLister *lister=0)
 Erase orphaned (attach count = 0) shared memory segments of a given type.
static bool exists (const char *magic_token, SharedMemoryHeader *header)
 Check if a specific shared memory segment exists.
static bool is_destroyed (int shm_id)
 Check if a segment has been destroyed.
static bool is_swapable (int shm_id)
 Check if memory can be swapped out.
static unsigned int num_attached (int shm_id)
 Get number of attached processes.
static SharedMemoryIterator find (const char *magic_token, SharedMemoryHeader *header)
 Find SharedMemory segments.
static SharedMemoryIterator end ()
 Get invalid iterator.

Static Public Attributes

static const unsigned int MagicTokenSize = 16
 The magic token size.
static const short MaxNumConcurrentReaders = 8
 Maximum number of concurrent readers.

Protected Member Functions

 SharedMemory (const char *magic_token, bool is_read_only, bool create, bool destroy_on_delete)
 Constructor for derivates.
void attach ()
 Attach to the shared memory segment.
void free ()
 Detach from and maybe destroy the shared memory segment.

Protected Attributes

void * _memptr
 Pointer to the data segment.
size_t _mem_size
 Total size of the segment, including headers.
size_t _data_size
 Size of the data segment only.
SharedMemoryHeader_header
 Data-specific header.
bool _is_read_only
 Read-only.
bool _destroy_on_delete
 destroy on delete.
bool _should_create
 Create shared memory segment.
char * _magic_token
 Magic token.
char * _shm_magic_token
 Magic token as stored in the shared memory segment.
SharedMemory_header_t_shm_header
 general header as stored in the shared memory segment
void * _shm_upper_bound
 Upper bound of memory.
long unsigned int _shm_offset
 Offset to the master's base addr.

Classes

struct  SharedMemory_header_t
 General header. More...
class  SharedMemoryIterator
 Shared Memory iterator. More...

Detailed Description

Shared memory segment.

This class gives access to shared memory segment to store arbitrary data. With shared memory data can be shared between several applications. Special means like semaphores have to be used to control access to the storage to prevent data corruption.

The shared memory segment is divided into three parts. 1. General shared memory header 2. Data-specific header 3. Data

The general header consists of a magic token of MagicTokenSize that is used to find the basically compatible shared memory segments out of all existing shared memory segments. This is done for convenience. Although in general shared memory is accessed via keys or IDs it is easier from the maintenance side to just scan the segments to find the correct one, especially if there may be more than just one segment for the same application. The header also includes a semaphore ID which is unused at the moment.

The data-specific header is generated from a given SharedMemoryHeader implementation. It can be used to store any information that is needed to identify a specific shared memory segment and to store management data for the data segment. It should always contain enough information to derive the data segment size or if needed an explicit information about the memory size.

The data segment can be filled with any data you like.

Shared memory segments are protected with a read-write lock implemented with two IPC semaphores. The writer takes preference in locking. Only a limited number of concurrent readers can be allowed. The constant MaxNumberConcurrentReaders defines how many these are. If a shared memory segment already has a semaphore assigned at the time it is opened this semaphore is automatically opened. In any case add_semaphore() can be used to create (or open if it already exists) a semaphore for the shared memory segment. Information about the semaphore is stored in the shared memory general header.

This class provides utilities to list, erase and check existence of given shared memory segments. For this often a SharedMemoryLister is used that takes care of formatting the output of the specific information about the shared memory segment.

See also:
SharedMemoryHeader

SharedMemorySegment

qa_shmem.cpp

Author:
Tim Niemueller

Definition at line 49 of file shm.h.


Constructor & Destructor Documentation

fawkes::SharedMemory::SharedMemory ( const char *  magic_token,
SharedMemoryHeader header,
bool  is_read_only,
bool  create,
bool  destroy_on_delete 
)

Create a new shared memory segment.

This will open a shared memory segment that exactly fits the given SharedMemoryHeader. It the segment does not exist and create is assured the segment is created from the given data, otherwise the SharedMemory instance remains in an invalid state and an exception is thrown. The segment can be destroyed automatically if the instance is destroyed. Shared memory segments can be opened read-only.

Parameters:
magic_token This is the magic token discussed above that is used to identify the shared memory segment. The magic_token can be of arbitrary size but at most MagicTokenSize bytes are used.
header The data-sepcific header used for this shared memory segment
is_read_only if true the shared memory segment is opened in read-only mode
create if true the shared memory segment is created if no one matching the headers was found
destroy_on_delete if true the shared memory segment is destroyed when this SharedMemory instance is deleted.
Exceptions:
ShmNoHeaderException No header has been set
ShmInconsistentSegmentSizeException The memory size is not the expected memory size
ShmCouldNotAttachException Could not attach to shared memory segment

Definition at line 333 of file shm.cpp.

References _data_size, _destroy_on_delete, _header, _is_read_only, _magic_token, _memptr, _shm_header, _shm_magic_token, _should_create, fawkes::Exception::append(), attach(), and MagicTokenSize.

fawkes::SharedMemory::SharedMemory ( const SharedMemory s  ) 

Copy constructor.

If the given SharedMemory was attached this instance will also attach.

Parameters:
s SharedMemory instance to copy.

Definition at line 271 of file shm.cpp.

References _data_size, _destroy_on_delete, _header, _is_read_only, _magic_token, _memptr, _shm_header, _shm_magic_token, _should_create, fawkes::Exception::append(), attach(), fawkes::SharedMemoryHeader::clone(), and MagicTokenSize.

fawkes::SharedMemory::~SharedMemory (  )  [virtual]

Destructor.

Definition at line 373 of file shm.cpp.

References _destroy_on_delete, _is_read_only, _magic_token, _shm_header, free(), fawkes::SharedMemory::SharedMemory_header_t::semaphore, and fawkes::SemaphoreSet::set_destroy_on_delete().

fawkes::SharedMemory::SharedMemory ( const char *  magic_token,
bool  is_read_only,
bool  create,
bool  destroy_on_delete 
) [protected]

Constructor for derivates.

This constructor may only be used by derivatives. It can be used to delay the call to attach() to do other preparations like creating a SharedMemoryHeader object.

Parameters:
magic_token magic token of the shared memory segment
is_read_only if true the shared memory segment is opened in read-only mode
create if true the shared memory segment is created if no one matching the headers was found
destroy_on_delete if true the shared memory segment is destroyed when this SharedMemory instance is deleted.

Definition at line 238 of file shm.cpp.

References _data_size, _destroy_on_delete, _header, _is_read_only, _magic_token, _memptr, _shm_header, _shm_magic_token, _should_create, and MagicTokenSize.


Member Function Documentation

void fawkes::SharedMemory::add_semaphore (  ) 

Add semaphore to shared memory segment.

This adds a semaphore to the system and puts its key in the shared memory segment header. The semaphore can then be protected via the semaphore by appropriate locking. If a semaphore has been assigned to the shared memory segment already but after the segment was opened the semaphore is opened and no new semaphore is created.

Definition at line 766 of file shm.cpp.

References _is_read_only, _memptr, _shm_header, fawkes::SemaphoreSet::key(), MaxNumConcurrentReaders, fawkes::SharedMemory::SharedMemory_header_t::semaphore, fawkes::SemaphoreSet::set_value(), and fawkes::SemaphoreSet::unlock().

Referenced by attach(), fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager(), and firevision::SharedMemoryImageBuffer::SharedMemoryImageBuffer().

void * fawkes::SharedMemory::addr ( void *  ptr  ) 

Get an address from a real pointer.

If there is address-dependent data in the shared memory segment (like pointers to the next element in a linked list) these are only valid for the process that created the shared memory segment, they are not necessarily valid for other processes.

This method takes a pointer that points to data in the shared memory segment that is valid in the local process and transform it to a pointer that is valid inside the shared memory segment with respect to the base address used by the creating process.

Parameters:
ptr pointer to data inside the shared memory segment
Returns:
memory address valid for the creator of the shared memory segment
Exceptions:
ShmPtrOutOfBoundsException This exception is thrown if ptr is not NULL, smaller than the local base ptr and greater or equal to the local base ptr plus the memory size.
See also:
ptr()

Definition at line 613 of file shm.cpp.

References _shm_offset.

Referenced by fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager(), fawkes::BlackBoardSharedMemoryHeader::set_alloc_list_head(), and fawkes::BlackBoardSharedMemoryHeader::set_free_list_head().

void fawkes::SharedMemory::attach (  )  [protected]

Attach to the shared memory segment.

This method will try to open and/or create the shared memory segment.

Exceptions:
ShmNoHeaderException No header has been set
ShmInconsistentSegmentSizeException The memory size is not the expected memory size
ShmCouldNotAttachException Could not attach to shared memory segment

Definition at line 420 of file shm.cpp.

References _data_size, _header, _is_read_only, _magic_token, _mem_size, _memptr, _shm_header, _shm_magic_token, _shm_offset, _shm_upper_bound, _should_create, add_semaphore(), fawkes::SharedMemoryHeader::data_size(), fawkes::SharedMemoryHeader::initialize(), MagicTokenSize, fawkes::SharedMemoryHeader::matches(), fawkes::SharedMemory::SharedMemory_header_t::semaphore, fawkes::SharedMemoryHeader::set(), fawkes::SharedMemory::SharedMemory_header_t::shm_addr, and fawkes::SharedMemoryHeader::size().

Referenced by firevision::SharedMemoryImageBuffer::set_image_id(), firevision::SharedMemoryLookupTable::set_lut_id(), and SharedMemory().

size_t fawkes::SharedMemory::data_size (  ) 

Get the size of the data-segment.

Use this method to get the size of the data segment. Calls dataSize() of the data-specific header internally.

Returns:
size of the data-segment in bytes

Definition at line 670 of file shm.cpp.

References _data_size.

Referenced by firevision::SharedMemoryCamera::capture().

SharedMemory::SharedMemoryIterator fawkes::SharedMemory::end (  )  [static]

Get invalid iterator.

Returns an iterator to a non-existing element.

Returns:
Non-existing element

Definition at line 1191 of file shm.cpp.

Referenced by erase(), erase_orphaned(), exists(), and list().

void fawkes::SharedMemory::erase ( const char *  magic_token,
SharedMemoryHeader header,
SharedMemoryLister lister = 0 
) [static]

Erase shared memory segments of a given type.

This method erases (destroys) all shared memory segments that match the given magic token (first MagicTokenSize bytes, filled with zero) and the given header. The lister is called to format the output. If a semaphore has been assigned to this shared memory segment it is destroyed as well.

Parameters:
magic_token Token to look for
header header to identify interesting segments with matching magic_token
lister Lister used to format output, maybe NULL (default)

Definition at line 1065 of file shm.cpp.

References fawkes::SemaphoreSet::destroy(), end(), find(), fawkes::SharedMemoryLister::print_footer(), fawkes::SharedMemoryLister::print_header(), fawkes::SharedMemoryLister::print_info(), fawkes::SharedMemoryLister::print_no_segments(), fawkes::SharedMemory::SharedMemoryIterator::semaphore(), and fawkes::SharedMemory::SharedMemoryIterator::shmid().

void fawkes::SharedMemory::erase_orphaned ( const char *  magic_token,
SharedMemoryHeader header,
SharedMemoryLister lister = 0 
) [static]

Erase orphaned (attach count = 0) shared memory segments of a given type.

This method erases (destroys) all shared memory segments that match the given magic token (first MagicTokenSize bytes, filled with zero) and the given header and where no process is attached to. If a semaphore has been assigned to this shared memory segment it is destroyed as well. The lister is called to format the output.

Parameters:
magic_token Token to look for
header header to identify interesting segments with matching magic_token
lister Lister used to format output, maybe NULL (default)

Definition at line 1111 of file shm.cpp.

References fawkes::SemaphoreSet::destroy(), end(), find(), fawkes::SharedMemoryLister::print_footer(), fawkes::SharedMemoryLister::print_header(), fawkes::SharedMemoryLister::print_info(), fawkes::SharedMemoryLister::print_no_orphaned_segments(), fawkes::SharedMemoryLister::print_no_segments(), fawkes::SharedMemory::SharedMemoryIterator::segmnattch(), fawkes::SharedMemory::SharedMemoryIterator::semaphore(), and fawkes::SharedMemory::SharedMemoryIterator::shmid().

Referenced by fawkes::LocalBlackBoard::cleanup().

bool fawkes::SharedMemory::exists ( const char *  magic_token,
SharedMemoryHeader header 
) [static]

Check if a specific shared memory segment exists.

This method will search for a memory chunk that matches the given magic token and header.

Parameters:
magic_token Token to look for
header header to identify interesting segments with matching magic_token
Returns:
true, if a matching shared memory segment was found, else otherwise

Definition at line 1166 of file shm.cpp.

References end(), and find().

SharedMemory::SharedMemoryIterator fawkes::SharedMemory::find ( const char *  magic_token,
SharedMemoryHeader header 
) [static]

Find SharedMemory segments.

Find SharedMemory segments identified by the supplied magic_token and header.

Parameters:
magic_token magic token
header shared memory header
Returns:
iterator pointing to the first found element (or end() if none found)

Definition at line 1180 of file shm.cpp.

Referenced by erase(), erase_orphaned(), exists(), and list().

void fawkes::SharedMemory::free (  )  [protected]

Detach from and maybe destroy the shared memory segment.

This will detach from the shared memory segment. If destroy_on_delete is true this will destroy the shared memory segment before detaching.

Definition at line 394 of file shm.cpp.

References _destroy_on_delete, _is_read_only, _memptr, _shm_header, and _shm_magic_token.

Referenced by firevision::SharedMemoryImageBuffer::set_image_id(), firevision::SharedMemoryLookupTable::set_lut_id(), ~SharedMemory(), firevision::SharedMemoryImageBuffer::~SharedMemoryImageBuffer(), fawkes::SharedMemory::SharedMemoryIterator::~SharedMemoryIterator(), and firevision::SharedMemoryLookupTable::~SharedMemoryLookupTable().

bool fawkes::SharedMemory::is_creator (  ) 

Determine if the shared memory segment has been created by this instance.

In some situations you want to know if the current instance has created the shared memory segment or if it attached to an existing shared memory segment. This is handy for example in master-slave constellations where one process is the master over a given shared memory segment and other slaves may read but need special means to alter the data. This is a somewhat softer variant of exclusive access.

Returns:
true, if this instance of SharedMemory created the segment, false otherwise

Definition at line 646 of file shm.cpp.

Referenced by fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager().

bool fawkes::SharedMemory::is_destroyed ( int  shm_id  )  [static]

Check if a segment has been destroyed.

Check for a shared memory segment of the given ID.

Parameters:
shm_id ID of the shared memory segment.
Returns:
true, if the shared memory segment is marked as destroyed or does not exist at all, false otherwise.

Definition at line 965 of file shm.cpp.

bool fawkes::SharedMemory::is_destroyed (  ) 

Check if segment has been destroyed This can be used if the segment has been destroyed.

This means that no other process can connect to the shared memory segment. As long as some process is attached to the shared memory segment the segment will still show up in the list

Returns:
true, if this shared memory segment has been destroyed, false otherwise

Definition at line 697 of file shm.cpp.

Referenced by fawkes::BlackBoardSharedMemoryLister::print_info().

bool fawkes::SharedMemory::is_protected (  ) 

Check if memory segment is protected.

This method can be used to determine if a semaphore has been associated to this shared memory segment. Locking is not guaranteed, it depends on the application. Use lock(), tryLock() and unlock() appropriately. You can do this always, also if you start with unprotected memory. The operations are just noops in that case. Protection can be enabled by calling add_semaphore(). If a memory segment was protected when it was opened it is automatically opened in protected mode.

Returns:
true, if semaphore is associated to memory, false otherwise

Definition at line 739 of file shm.cpp.

bool fawkes::SharedMemory::is_read_only (  ) 

Check for read-only mode.

Returns:
true, if the segment is opened in read-only mode, false otherwise

Definition at line 629 of file shm.cpp.

References _is_read_only.

bool fawkes::SharedMemory::is_swapable ( int  shm_id  )  [static]

Check if memory can be swapped out.

This method can be used to check if the memory can be swapped.

Parameters:
shm_id ID of the shared memory segment.
Returns:
true, if the memory can be swapped, false otherwise

Definition at line 988 of file shm.cpp.

bool fawkes::SharedMemory::is_swapable (  ) 

Check if memory can be swapped out.

This method can be used to check if the memory can be swapped.

Returns:
true, if the memory can be swapped, false otherwise

Definition at line 708 of file shm.cpp.

Referenced by fawkes::BlackBoardSharedMemoryLister::print_info().

bool fawkes::SharedMemory::is_valid (  ) 

Check validity of shared memory segment.

Use this to check if the shared memory segmentis valid. That means that this instance is attached to the shared memory and data can be read from or written to the memptr.

Returns:
true, if the shared memory segment is valid and can be utilized, false otherwise

Definition at line 722 of file shm.cpp.

References _memptr.

Referenced by fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager(), FvRetrieverThread::init(), and MiniImageProducer::MiniImageProducer().

void fawkes::SharedMemory::list ( const char *  magic_token,
SharedMemoryHeader header,
SharedMemoryLister lister 
) [static]

List shared memory segments of a given type.

This method lists all shared memory segments that match the given magic token (first MagicTokenSize bytes, filled with zero) and the given header. The lister is called to format the output.

Parameters:
magic_token Token to look for
header header to identify interesting segments with matching magic_token
lister Lister used to format output

Definition at line 1032 of file shm.cpp.

References end(), find(), fawkes::SharedMemoryLister::print_footer(), fawkes::SharedMemoryLister::print_header(), fawkes::SharedMemoryLister::print_info(), fawkes::SharedMemoryLister::print_no_segments(), and fawkes::SharedMemory::SharedMemoryIterator::shmid().

void fawkes::SharedMemory::lock_for_read (  ) 

Lock shared memory segment for reading.

If the shared memory segment is protected by an associated semaphore it can be locked with this semaphore by calling this method.

See also:
isProtected()

unlock()

try_lock_for_read()

Definition at line 821 of file shm.cpp.

References fawkes::SemaphoreSet::lock().

Referenced by firevision::SharedMemoryCamera::capture(), firevision::FuseImageContent::FuseImageContent(), and firevision::SharedMemoryCamera::lock_for_read().

void fawkes::SharedMemory::lock_for_write (  ) 

Lock shared memory segment for writing.

If the shared memory segment is protected by an associated semaphore it can be locked with this semaphore by calling this method.

See also:
is_protected()

unlock()

try_lock_for_read()

Definition at line 872 of file shm.cpp.

References fawkes::SemaphoreSet::lock(), MaxNumConcurrentReaders, and fawkes::SemaphoreSet::unlock().

Referenced by fawkes::BlackBoardMemoryManager::alloc(), fawkes::BlackBoardMemoryManager::free(), fawkes::BlackBoardMemoryManager::lock(), and firevision::SharedMemoryCamera::lock_for_write().

void * fawkes::SharedMemory::memptr (  ) 

Get a pointer to the shared memory This method returns a pointer to the data-segment of the shared memory segment.

It has the size stated as dataSize() from the header.

Returns:
pointer to the data-segment
See also:
getDataSize()

Definition at line 658 of file shm.cpp.

References _memptr.

Referenced by fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager().

unsigned int fawkes::SharedMemory::num_attached ( int  shm_id  )  [static]

Get number of attached processes.

Parameters:
shm_id ID of the shared memory segment.
Returns:
number of attached processes

Definition at line 1010 of file shm.cpp.

Referenced by fawkes::BlackBoardSharedMemoryLister::print_info().

void * fawkes::SharedMemory::ptr ( void *  addr  ) 

Get the real pointer to the data based on an address.

If there is address-dependent data in the shared memory segment (like pointers to the next element in a linked list) these are only valid for the process that created the shared memory segment, they are not necessarily valid for other processes.

The function takes an address that has been stored in the shared memory segment and transforms it into a valid local pointer. Not that this does only work with pointers inside the shared memory segment. You can only tranform addresses that point to somewhere inside the shared memory segment!

We could also have added local offsets, starting with 0 at the beginning of the shared memory segment. We decided against this since our major our main concern is that this works fast for the master, because this will be the Fawkes main application, and for attached processes it may work slower and we don't care.

Parameters:
addr memory address read from the shared memory segment
Returns:
pointer inside the shared memory segment
Exceptions:
ShmAddrOutOfBoundsException This exception is thrown if addr is not NULL, smaller than the base addr and greater or equal to the base addr plus the memory size.
See also:
addr()

Definition at line 582 of file shm.cpp.

References _shm_offset, and _shm_upper_bound.

Referenced by fawkes::BlackBoardSharedMemoryHeader::alloc_list_head(), fawkes::BlackBoardSharedMemoryHeader::free_list_head(), and fawkes::BlackBoardMemoryManager::ChunkIterator::operator *().

void fawkes::SharedMemory::set ( void *  memptr  ) 

Copies data from the memptr to shared memory.

Use this method to copy data from the given external memptr to the data segment of the shared memory.

Parameters:
memptr the memptr to copy from

Definition at line 682 of file shm.cpp.

References _data_size, and _memptr.

void fawkes::SharedMemory::set_destroy_on_delete ( bool  destroy  ) 

Set deletion behaviour.

This has the same effect as the destroy_on_delete parameter given to the constructor.

Parameters:
destroy set to true to destroy the shared memory segment on deletion

Definition at line 752 of file shm.cpp.

References _destroy_on_delete.

Referenced by fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager().

void fawkes::SharedMemory::set_swapable ( bool  swapable  ) 

Set shared memory swapable.

Setting memory unswapable (in terms of Linux memory management: lock all pages related to this memory segment) will only succeed for very small portions of memory. A resource limit is implied (see getrlimit(2)). In most cases the maximum amout of locked memory is about 32 KB.

Parameters:
swapable set to true, if memory should be allowed to be swaped out.

Definition at line 803 of file shm.cpp.

Referenced by fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager().

bool fawkes::SharedMemory::try_lock_for_read (  ) 

Try to aquire lock on shared memory segment for reading.

If the shared memory segment is protected by an associated semaphore it can be locked. With tryLock() you can try to aquire the lock, but the method will not block if it cannot get the lock but simply return false. This can be used to detect if memory is locked:

 if (mem->tryLock()) {
   // was not locked
   mem->unlock();
 } else {
   // is locked
 }
Returns:
true if the lock was acquired for reading, false if lock was not acquired.
See also:
isProtected()

unlock()

lock()

Definition at line 851 of file shm.cpp.

References fawkes::SemaphoreSet::try_lock().

Referenced by firevision::SharedMemoryCamera::try_lock_for_read().

bool fawkes::SharedMemory::try_lock_for_write (  ) 

Try to aquire lock on shared memory segment for writing.

If the shared memory segment is protected by an associated semaphore it can be locked. With tryLock() you can try to aquire the lock, but the method will not block if it cannot get the lock but simply return false. This can be used to detect if memory is locked:

 if (mem->tryLock()) {
   // was not locked
   mem->unlock();
 } else {
   // is locked
 }
Returns:
true if the lock was acquired for writing, false if lock was not acquired.
See also:
isProtected()

unlock()

lock()

Definition at line 907 of file shm.cpp.

References MaxNumConcurrentReaders, fawkes::SemaphoreSet::try_lock(), and fawkes::SemaphoreSet::unlock().

Referenced by firevision::SharedMemoryCamera::try_lock_for_write().

void fawkes::SharedMemory::unlock (  ) 

Unlock memory.

If the shared memory segment is protected by an associated semaphore it can be locked. With unlock() you lift the lock on the memory. Be aware that unlocking a not-locked piece of memory will result in havoc and insanity! Have only exactly guaranteed pairs of lock/successful tryLock() and unlock()!

Definition at line 939 of file shm.cpp.

References MaxNumConcurrentReaders, and fawkes::SemaphoreSet::unlock().

Referenced by fawkes::BlackBoardMemoryManager::alloc(), firevision::SharedMemoryCamera::capture(), fawkes::BlackBoardMemoryManager::free(), firevision::FuseImageContent::FuseImageContent(), fawkes::BlackBoardMemoryManager::unlock(), and firevision::SharedMemoryCamera::unlock().


Member Data Documentation

fawkes::SharedMemory::_data_size [protected]

Size of the data segment only.

Definition at line 166 of file shm.h.

Referenced by attach(), data_size(), set(), and SharedMemory().

fawkes::SharedMemory::_destroy_on_delete [protected]

destroy on delete.

If true before free() segment is destroyed.

Definition at line 169 of file shm.h.

Referenced by free(), set_destroy_on_delete(), SharedMemory(), and ~SharedMemory().

fawkes::SharedMemory::_header [protected]

Data-specific header.

Definition at line 167 of file shm.h.

Referenced by attach(), and SharedMemory().

fawkes::SharedMemory::_is_read_only [protected]

Read-only.

if true before attach() open segment read-only

Definition at line 168 of file shm.h.

Referenced by add_semaphore(), attach(), free(), is_read_only(), firevision::SharedMemoryImageBuffer::set_capture_time(), firevision::SharedMemoryImageBuffer::set_circle(), firevision::SharedMemoryImageBuffer::set_circle_radius(), firevision::SharedMemoryImageBuffer::set_circle_x(), firevision::SharedMemoryImageBuffer::set_circle_y(), firevision::SharedMemoryImageBuffer::set_roi(), firevision::SharedMemoryImageBuffer::set_roi_height(), firevision::SharedMemoryImageBuffer::set_roi_width(), firevision::SharedMemoryImageBuffer::set_roi_x(), firevision::SharedMemoryImageBuffer::set_roi_y(), SharedMemory(), and ~SharedMemory().

fawkes::SharedMemory::_magic_token [protected]

Magic token.

Definition at line 171 of file shm.h.

Referenced by attach(), SharedMemory(), and ~SharedMemory().

fawkes::SharedMemory::_mem_size [protected]

Total size of the segment, including headers.

Definition at line 165 of file shm.h.

Referenced by attach().

fawkes::SharedMemory::_memptr [protected]

Pointer to the data segment.

Definition at line 164 of file shm.h.

Referenced by add_semaphore(), attach(), firevision::SharedMemoryLookupTable::buffer(), firevision::SharedMemoryImageBuffer::buffer(), free(), is_valid(), memptr(), set(), firevision::SharedMemoryImageBuffer::set_image_id(), firevision::SharedMemoryLookupTable::set_lut_id(), and SharedMemory().

fawkes::SharedMemory::_shm_header [protected]

general header as stored in the shared memory segment

Definition at line 173 of file shm.h.

Referenced by add_semaphore(), attach(), free(), SharedMemory(), and ~SharedMemory().

fawkes::SharedMemory::_shm_magic_token [protected]

Magic token as stored in the shared memory segment.

Definition at line 172 of file shm.h.

Referenced by attach(), free(), and SharedMemory().

fawkes::SharedMemory::_shm_offset [protected]

Offset to the master's base addr.

Definition at line 175 of file shm.h.

Referenced by addr(), attach(), and ptr().

fawkes::SharedMemory::_shm_upper_bound [protected]

Upper bound of memory.

Used by ptr to determine if the given address is valid.

Definition at line 174 of file shm.h.

Referenced by attach(), and ptr().

fawkes::SharedMemory::_should_create [protected]

Create shared memory segment.

If true before attach shared memory segment is created if it does not exist.

Definition at line 170 of file shm.h.

Referenced by attach(), and SharedMemory().

const unsigned int fawkes::SharedMemory::MagicTokenSize = 16 [static]

The magic token size.

Your magic token identifier may have an arbitrary size. It is truncated at MagicTokenSize bytes or filled with zeros up to a length of MagicTokenSize bytes.

Definition at line 54 of file shm.h.

Referenced by attach(), fawkes::SharedMemory::SharedMemoryIterator::operator++(), and SharedMemory().

const short fawkes::SharedMemory::MaxNumConcurrentReaders = 8 [static]

Maximum number of concurrent readers.

This constant defines how many readers may concurrently read from shared memory segments.

Definition at line 55 of file shm.h.

Referenced by add_semaphore(), lock_for_write(), try_lock_for_write(), and unlock().


The documentation for this class was generated from the following files:
Generated on Tue Feb 22 13:32:54 2011 for Fawkes API by  doxygen 1.4.7