Fawkes API  Fawkes Development Version
fawkes::BlackBoardMemoryManager Class Reference

BlackBoard memory manager. More...

#include <>>

Classes

class  ChunkIterator
 Iterator for memory chunks. More...
 

Public Member Functions

 BlackBoardMemoryManager (size_t memsize)
 Heap Memory Constructor. More...
 
 BlackBoardMemoryManager (size_t memsize, unsigned int version, bool use_shmem, const char *shmem_token="FawkesBlackBoard")
 Shared Memory Constructor. More...
 
 ~BlackBoardMemoryManager ()
 Destructor. More...
 
void * alloc (unsigned int num_bytes)
 Allocate memory. More...
 
void free (void *chunk_ptr)
 Free a memory chunk. More...
 
void check ()
 Check memory consistency. More...
 
bool is_master () const
 Check if this BB memory manager is the master. More...
 
unsigned int max_free_size () const
 Get maximum allocatable memory size. More...
 
unsigned int max_allocated_size () const
 Get maximum alloced memory size. More...
 
unsigned int free_size () const
 Get total free memory. More...
 
unsigned int allocated_size () const
 Get total allocated memory. More...
 
unsigned int overhang_size () const
 Get number of overhanging bytes. More...
 
unsigned int num_free_chunks () const
 Get number of free chunks. More...
 
unsigned int num_allocated_chunks () const
 Get number of allocated chunks. More...
 
unsigned int memory_size () const
 Get size of memory. More...
 
unsigned int version () const
 Get BlackBoard version. More...
 
void print_free_chunks_info () const
 Print out info about free chunks. More...
 
void print_allocated_chunks_info () const
 Print out info about allocated chunks. More...
 
void print_performance_info () const
 Prints out performance info. More...
 
void lock ()
 Lock memory. More...
 
bool try_lock ()
 Try to lock memory. More...
 
void unlock ()
 Unlock memory. More...
 
ChunkIterator begin ()
 Get first element for chunk iteration. More...
 
ChunkIterator end ()
 Get end of chunk list. More...
 

Friends

class BlackBoardInterfaceManager
 

Detailed Description

BlackBoard memory manager.

This class is used by the BlackBoard to manage the memory in the shared memory segment. A simple strategy is used for memory management as the expected use case is rather simple as well.

The memory is allocated as one big chunk of contiguous memory. Inside this chunk the memory manager handles the smaller chunks that are allocated in this region. The chunk is allocated as shared memory segment to allow for multi-process usage of the memory.

The memory is organized in two separate lists. The one is the free chunks list and the other one the allocated chunks list. After startup the allocated chunks list is empty while the free chunks list contains one and only one big chunk of free memory that contains the whole data segment.

When memory is allocated the smallest chunk that is big enough for the requested chunk is used. It is then removed from the free list. If the chunk is big enough to hold another chunk of memory (the remaining size can accomodate the header and at least as many bytes as the header is in size) the chunk is split into an exactly fitting allocated chunk and a remaining free chunk. The chunks are then added to the appropriate lists. If there is more memory then requested but not enough memory to make it a new free chunk the allocated chunk is enlarged to fill the whole chunk. The additional bytes are recorded as overhanging bytes.

When memory is freed the chunk is removed from the allocated chunks list and added to the free chunks list. Then the list is cleaned up and adjacent regions of free memory are merged to one. Afterwards the free chunks list will contain non-ajdacent free memory regions of maximum size between allocated chunks.

The memory manager is thread-safe as all appropriate operations are protected by a mutex.

The memory manager has also been prepared for multi-process usage of the shared memory region. but up to now only one process may use the shared memory segment.

Todo:
implement multi-process feature
Author
Tim Niemueller
See also
SharedMemory
Mutex

Definition at line 56 of file memory_manager.h.

Constructor & Destructor Documentation

◆ BlackBoardMemoryManager() [1/2]

fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager ( size_t  memsize)

Heap Memory Constructor.

Constructs a memory segment on the heap.

Parameters
memsizememory size

Definition at line 107 of file memory_manager.cpp.

References fawkes::chunk_list_t::next, fawkes::chunk_list_t::overhang, fawkes::chunk_list_t::ptr, and fawkes::chunk_list_t::size.

◆ BlackBoardMemoryManager() [2/2]

fawkes::BlackBoardMemoryManager::BlackBoardMemoryManager ( size_t  memsize,
unsigned int  version,
bool  master,
const char *  shmem_token = "FawkesBlackBoard" 
)

Shared Memory Constructor.

Parameters
memsizethe size of the shared memory segment (data without header) that is being managed.
versionversion of the BlackBoard
mastermaster mode, this memory manager has to be owner of shared memory segment
shmem_tokenshared memory token, passed to SharedMemory
Exceptions
BBMemMgrNotMasterExceptionA matching shared memory segment has already been created.
See also
SharedMemory::SharedMemory()

Definition at line 140 of file memory_manager.cpp.

References fawkes::SharedMemory::add_semaphore(), fawkes::SharedMemory::addr(), fawkes::SharedMemory::is_creator(), fawkes::SharedMemory::is_valid(), fawkes::SharedMemory::memptr(), fawkes::chunk_list_t::next, fawkes::chunk_list_t::overhang, fawkes::chunk_list_t::ptr, fawkes::BlackBoardSharedMemoryHeader::set_alloc_list_head(), fawkes::SharedMemory::set_destroy_on_delete(), fawkes::BlackBoardSharedMemoryHeader::set_free_list_head(), fawkes::BlackBoardSharedMemoryHeader::set_shared_memory(), fawkes::SharedMemory::set_swapable(), and fawkes::chunk_list_t::size.

◆ ~BlackBoardMemoryManager()

Member Function Documentation

◆ alloc()

void * fawkes::BlackBoardMemoryManager::alloc ( unsigned int  num_bytes)

Allocate memory.

This will allocate memory in the shared memory segment. The strategy is described in the class description.

Exceptions
OutOfMemoryExceptionthrown if not enough free memory is available to accommodate a chunk of the desired size
Parameters
num_bytesnumber of bytes to allocate
Returns
pointer to the memory chunk

Definition at line 310 of file memory_manager.cpp.

References fawkes::Mutex::lock(), fawkes::SharedMemory::lock_for_write(), fawkes::Mutex::unlock(), and fawkes::SharedMemory::unlock().

◆ allocated_size()

unsigned int fawkes::BlackBoardMemoryManager::allocated_size ( ) const

Get total allocated memory.

This method gives information about the sum of all allocated chunk sizes.

Returns
sum of allocated chunks sizes

Definition at line 540 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head(), fawkes::chunk_list_t::next, and fawkes::chunk_list_t::size.

◆ begin()

◆ check()

void fawkes::BlackBoardMemoryManager::check ( )

Check memory consistency.

This method checks the consistency of the memory segment. It controls whether all the memory is covered by the free and allocated chunks lists and if there is no unmanaged memory between chunks.

Exceptions
BBInconsistentMemoryExceptionthrown if the memory segment has been corrupted. Contains descriptive message.

Definition at line 392 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head(), fawkes::BlackBoardSharedMemoryHeader::free_list_head(), fawkes::chunk_list_t::next, fawkes::chunk_list_t::ptr, and fawkes::chunk_list_t::size.

◆ end()

BlackBoardMemoryManager::ChunkIterator fawkes::BlackBoardMemoryManager::end ( )

Get end of chunk list.

This returns an iterator that points to the element just beyond the allocated chunk list.

Returns
ChunkIterator pointing to a non-existant element beyond the chunk list

Definition at line 890 of file memory_manager.cpp.

Referenced by fawkes::BlackBoardInterfaceManager::list(), fawkes::BlackBoardInterfaceManager::list_all(), fawkes::BlackBoardInterfaceManager::open_multiple_for_reading(), and fawkes::BlackBoardInterfaceManager::~BlackBoardInterfaceManager().

◆ free()

void fawkes::BlackBoardMemoryManager::free ( void *  ptr)

Free a memory chunk.

Frees a previously allocated chunk. Not that you have to give the exact pointer that was returned by alloc(). You may not give a pointer inside a memory chunk or even worse outside of it! See the class description for a brief description of the strategy used.

Parameters
ptrpointer to the chunk of memory
Exceptions
BlackBoardMemMgrInvalidPointerExceptiona pointer that has not been previously returned by alloc() has been given and could not be found in the allocated chunks list.

Definition at line 339 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head(), fawkes::BlackBoardSharedMemoryHeader::free_list_head(), fawkes::Mutex::lock(), fawkes::SharedMemory::lock_for_write(), fawkes::chunk_list_t::overhang, fawkes::BlackBoardSharedMemoryHeader::set_alloc_list_head(), fawkes::BlackBoardSharedMemoryHeader::set_free_list_head(), fawkes::Mutex::unlock(), and fawkes::SharedMemory::unlock().

Referenced by fawkes::BlackBoardInterfaceManager::close(), and ~BlackBoardMemoryManager().

◆ free_size()

unsigned int fawkes::BlackBoardMemoryManager::free_size ( ) const

Get total free memory.

This method gives information about the sum of all free chunk sizes. Note that it is not guaranteed that that much data can be stored in the memory since fragmentation may have occured. To get information about the biggest piece of memory that you can allocate use getMaxFreeSize()

Returns
sum of free chunk sizes

Definition at line 523 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::free_list_head(), fawkes::chunk_list_t::next, and fawkes::chunk_list_t::size.

◆ is_master()

bool fawkes::BlackBoardMemoryManager::is_master ( ) const

Check if this BB memory manager is the master.

Returns
true if this BB memory manager instance is the master for the BB shared memory segment, false otherwise

Definition at line 457 of file memory_manager.cpp.

Referenced by fawkes::BlackBoardInterfaceManager::~BlackBoardInterfaceManager().

◆ lock()

void fawkes::BlackBoardMemoryManager::lock ( )

Lock memory.

Locks the whole memory segment used and managed by the memory manager. Will aquire local mutex lock and global semaphore lock in shared memory segment.

Definition at line 598 of file memory_manager.cpp.

References fawkes::Mutex::lock(), and fawkes::SharedMemory::lock_for_write().

Referenced by fawkes::BlackBoardInterfaceManager::list(), fawkes::BlackBoardInterfaceManager::list_all(), fawkes::BlackBoardInterfaceManager::open_for_reading(), fawkes::BlackBoardInterfaceManager::open_for_writing(), and fawkes::BlackBoardInterfaceManager::open_multiple_for_reading().

◆ max_allocated_size()

unsigned int fawkes::BlackBoardMemoryManager::max_allocated_size ( ) const

Get maximum alloced memory size.

This method gives information about the maximum allocated chunk size and thus the maximum of memory that has been be allocated in one chunk.

Returns
maximum allocated chunk size

Definition at line 647 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head(), and fawkes::chunk_list_t::size.

Referenced by print_performance_info().

◆ max_free_size()

unsigned int fawkes::BlackBoardMemoryManager::max_free_size ( ) const

Get maximum allocatable memory size.

This method gives information about the maximum free chunk size and thus the maximum of memory that can be allocated in one chunk.

Returns
maximum free chunk size

Definition at line 504 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::free_list_head(), and fawkes::chunk_list_t::size.

Referenced by print_performance_info().

◆ memory_size()

unsigned int fawkes::BlackBoardMemoryManager::memory_size ( ) const

Get size of memory.

This does not include memory headers, but only the size of the data segment.

Returns
size of memory.

Definition at line 577 of file memory_manager.cpp.

◆ num_allocated_chunks()

unsigned int fawkes::BlackBoardMemoryManager::num_allocated_chunks ( ) const

Get number of allocated chunks.

Returns
number of allocated memory chunks

Definition at line 556 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head().

◆ num_free_chunks()

unsigned int fawkes::BlackBoardMemoryManager::num_free_chunks ( ) const

Get number of free chunks.

Returns
number of free memory chunks

Definition at line 566 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::free_list_head().

◆ overhang_size()

unsigned int fawkes::BlackBoardMemoryManager::overhang_size ( ) const

Get number of overhanging bytes.

The number of overhanging bytes. See class description for more info about overhanging bytes.

Returns
number of overhanging bytes

Definition at line 664 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head(), fawkes::BlackBoardSharedMemoryHeader::free_list_head(), fawkes::chunk_list_t::next, fawkes::chunk_list_t::overhang, fawkes::chunk_list_t::ptr, and fawkes::chunk_list_t::size.

Referenced by print_performance_info().

◆ print_allocated_chunks_info()

void fawkes::BlackBoardMemoryManager::print_allocated_chunks_info ( ) const

Print out info about allocated chunks.

Prints out a formatted list of allocated chunks.

Definition at line 477 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head().

◆ print_free_chunks_info()

void fawkes::BlackBoardMemoryManager::print_free_chunks_info ( ) const

Print out info about free chunks.

Prints out a formatted list of free chunks.

Definition at line 467 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::free_list_head().

◆ print_performance_info()

void fawkes::BlackBoardMemoryManager::print_performance_info ( ) const

Prints out performance info.

This will print out information about the number of free and allocated chunks, the maximum free and allocated chunk size and the number of overhanging bytes (see class description about overhanging bytes).

Definition at line 489 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::alloc_list_head(), fawkes::BlackBoardSharedMemoryHeader::free_list_head(), max_allocated_size(), max_free_size(), and overhang_size().

◆ try_lock()

bool fawkes::BlackBoardMemoryManager::try_lock ( )

Try to lock memory.

Tries to lock the whole memory segment used and managed by the memory manager. Will aquire local mutex lock and global semaphore lock in shared memory segment. The lock has been successfully aquired if both of these locks could be aquired!

Returns
true, if the lock could be aquired, false otherwise.

Definition at line 612 of file memory_manager.cpp.

References fawkes::Mutex::try_lock(), fawkes::SharedMemory::try_lock_for_write(), and fawkes::Mutex::unlock().

◆ unlock()

◆ version()

unsigned int fawkes::BlackBoardMemoryManager::version ( ) const

Get BlackBoard version.

Returns
BlackBoard version

Definition at line 587 of file memory_manager.cpp.

References fawkes::BlackBoardSharedMemoryHeader::version().


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