NAME

Sma - Shared memory allocator

SYNOPSIS

#include <codelibs/sma.h>
 class Sma
{
public:
Sma(void *base, size_t static_size = 0, size_t size = 0);
size_t alloc(size_t size);
void free(size_t offset);
};
 const size_t SMA_ALIGNMENT;
 inline size_t sma_align(size_t offset);
 CC ... -lcodelibs
 

DESCRIPTION

This class is used for allocating and deallocating blocks of memory within a shared memory segment.  The constructor for this class takes three optional arguments.  The first is the base address of the shared memory segment.  This should be the value that is returned by shmat(2). The static_size parameter is the number of bytes that should be left untouched at the beginning of the shared memory segment. 

The size parameter is the number of bytes in the shared memory segment that should be made available for allocated blocks.  The shared memory segment of the specified size will be initialized and made ready for allocation if the size value is greater than zero.  A non-zero size should only be specified by the process that creates the shared memory segment.  A value of zero for size should be used by all other processes to inhibit the initialization.  The size value should be at least 16 bytes in size.  It is also bumped up to 16 if it is smaller than 16 and greater than 0.  Typically, size is at least as big as the page size of the machine to be useful. 

alloc returns the byte offset from the shared memory base where a block of size bytes is located.  If the allocator is unable to find a block of memory large enough to hold size bytes then zero (0) will be returned as the offset.  If the allocator has not been initialized then -1 (cast to size_t) is returned.  Offsets returned by alloc are always properly aligned in multiples of SMA_ALIGNMENT (typically 8). 

free causes the block of memory at offset from the base of the shared memory segment to placed back in the free block pool. This makes the block available for future allocations.  If the block to be freed is adjacent to another already free block then the two blocks will be joined into one larger free block.  Offset MUST be a value that has been returned by alloc.

The function sma_align returns a value to be added to offset to make it aligned at SMA_ALIGNMENT. It does not return the new offset value - only the amount to be added to offset.  Thus the return value is always between zero and SMA_ALIGNMENT-1.

No provisions are made for synchronizing multiple processes that can potentially try to allocate or free blocks at the same time.  It is up to the user of this class to guarantee such synchronization.  The Mutex(3X) class should make this task easier.

FATAL ERRORS

The Sma constructor will abort with an error message if the base address of the shared memory segment itself is not properly aligned.  There’s really nothing Sma can do at this point anyway.  It will also fail if base plus static_size value is not properly aligned, since this would cause subsequent alloc calls to fail.  These values must be aligned on boundaries of SMA_ALIGNMENT bytes. 

NOTES

If the size parameter is less than the minimum allowed, it is set to the minimum segment size, which is 16 bytes. 

SEE ALSO

shget(2), shctl(2), shmat(2), mutex(3X), malloc(3).

  —