The class FBB::SharedMemory implements a usable interface to a shared
memory segment made available by FBB::SharedSegment and monitored by
FBB::SharedPos. It is the main building block for
FBB::SharedStreambuf, defining the `device' to which
FBB::SharedStreambuf interfaces. All shared memory related I/O should be
performed through an FBB::SharedMemory object, which is a true object, not
itself residing in shared memory. An FBB::SharedMemory object defines,
connects to and manages access to shared memory, encapsulating all raw shared
memory operations. In addition to the class FBB::SharedMemory the header
file bobcat/sharedmemory also defines a struct SharedEnum__ defining
an enum SizeUnit.
The total amount of requested shared memory is always a lower bound to the
actual amount of shared memory that eventually may become available. As a
fictitious example: assume 100 kB of memory is requested, then a table of,
e.g., 10 entries is maintained, each entry controlling the access to a shared
memory block of, 10 kB. These 10 kB blocks aren't immediately allocated,
but become available once the program reads from or writes to addresses
located in these data blocks. Whenever a data block is created it is
initialized to 0-bytes.
Caveat: when constructing a shared memory segment make sure the segment's
ID is stored at a retrievable location. This allows other processes to access
the shared segment. The shared segment ID is also required to delete a shared
memory segment. If the shared segment ID is lost, the memory occupied by the
shared memory segment remains inaccessible, and will reduce the amount of
usable memory until the computer is rebooted. The member function id
returns the ID of the shared memory currently monitored by an
FBB::SharedMemory object.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
FBB::SharedEnum__
The struct SharedEnum__ is a wrapper struct around enum SizeUnit,
which is available through inheritance in several FBB::Shared* classes,
and offers symbolic constants defining standard memory sizes. The enum
SizeUnit defines the following symbolic constants:
kB: , representing 210 bytes of memory;
MB: , representing 220 bytes of memory;
GB: , representing 230 bytes of memory
CONSTRUCTORS, DESTRUCTOR
SharedMemory():
The default constructor does not yet access a shared memory segment,
but can be used to define a stub FBB::SharedMemory object, to be
used at some later point during the execution of a program.
SharedMemory(size_t maxSize, SizeUnit sizeUnit, size_t access = 0600):
This constructor creates a shared memory segment having a capacity of
at least maxSize * sizeUnit bytes. The shared memory's access
rights are defined by the access parameter, using the well-known
(chmod(1)) way to define the access rights for the owner, the
group and others. If construction succeeds the shared memory is
ready for use. If construction fails, an FBB::Exception is
thrown.
SharedMemory(int id):
This constructor connects to a shared memory segment having ID
id. If construction succeeds the shared memory is ready for
use. If construction fails (e.g., no shared memory segment having ID
id exists), an FBB::Exception is thrown.
~SharedMemory():
The destructor detaches any attached shared memory segments from
the FBB::SharedMemory object. If the shared memory segment is
currently locked by the FBB::SharedMemory object, the lock is
removed.
copy and move constructors are not available.
OVERLOADED OPERATORS
std::ostream &operator<<(std::ostream &out,
SharedMemory const &sharedMemory):
The overloaded insertion operator inserts information about the
SharedMemory object into the provide ostream object. The IDs
of the shared segments, their sizes, the maximum number of shared
memory segments, the number of bytes that can be read from the shared
memory, and its actual storage capacity, etc., are displayed.
SharedMemory &operator=(SharedMemory &&rhs):
The overloaded move assignment operator is available. It is used to
(re)define the shared memory segment an FBB::SharedMemory object
is interfacing with.
The overloaded copy assignement operator is not available.
MEMBER FUNCTIONS
void clear():
First, the shared memory is locked. Next, all shared data segment are
deleted, and the shared memory's own data are reset to indicate it is
completely empty. Following this the shared memory segment is unlocked
again. Returning from clear the shared memory The
FBB::SharedMemory object is effectively re-initialized, with
offset and nReadable returning 0.
int get():
First the FBB::SharedMemory object calls lock to lock the
shared memory segment. Next the character at offset is retrieved
and offset is incremented. Then unlock is called, and the
retrieved character is returned. If offset is at least equal to
nReadable, EOF is immediately returned.
int id() const:
The ID of the shared memory segment is returned.
void kill():
Without locking the shared memory all shared memory controlled by the
FBB::SharedMemory object is deleted. The FBB::SharedMemory
object is unusable after returning from kill.
std::streamsize maxOffset() const:
The maximum possible offset that can be used with the shared memory
segment is returned. The members offset and nReadable
never exceed the value returned by maxOffset.
std::streamsize nReadable() const:
The number of characters (bytes) that can be read from the beginning of
the shared memory is returned.
std::streamsize offset() const:
The offset within the shared memory segment is returned.
char *ptr():
Returns 0 if offset() == maxOffset(). Otherwise it returns a
pointer to the character at index offset within the shared memory
segment.
int put(int ch):
After locking the appropriate shared data segment, ch is written at
position offset, incrementing offset thereafter. If ch ==
EOF, EOF is immediately returned.
int read(char *data, std::streamsize len):
While locking the appropriate shared data segment(s) at most len
bytes are read from the shared memory, starting at offset. The
bytes read from shared memory are stored at data. The number of
bytes actually written is returned. This member returns -1 if
initially offset was at least equal to nReadable.
void remove():
The shared memory is locked, after which all shared memory controlled
by the FBB::SharedMemory object is deleted. The
FBB::SharedMemory object is unusable after returning from
remove.
std::ios::pos_type seek(std::ios::off_type offset,
std::ios::seekdir way = std::ios::beg):
Moves the offset position relative to way. The value -1 is
returned when seeking before offset 0 or beyond maxOffset.
std::streamsize showmanyc() const:
The number of characters that can be read from the current shared
segment data block is returned. This member interrogates the number
of readable characters in the shared memory segment. This number may
change while this member is being executed. In order to receive a
stable return value, calling functions should have obtained a lock on
the shared memory segment before calling this member.
void swap(SharedMemory &other):
The current and other FBB::SharedMemory objects are swapped.
bool try_lock() const:
When returning true the current process has obtained the lock, and
the object's lock count is set to 1. Otherwise, false is returned
(which includes the case where the process already has obtained the
lock).
void unlock() const:
If the object's lock count is zero, the function immediately
returns. Otherwise, the object's lock count is decremented. Once the
lock count has decremented to zero the lock of the shared memory
segment is released.
int write(char const *data, std::streamsize len):
The FBB::SharedMemory object calls lock to lock the shared
memory, and writes at most len bytes into the shared memory,
starting at offset. Next, unlock is called. The number of
bytes actually written is returned. The member function returns -1 if
initially offset is equal to maxOffset.