The class FBB::SharedSegment implements the shared memory data
structure which is used by Bobcat's shared memory classes. Bobcat's
SharedMemory class accesses or defines a shared memory segment which is
interpreted as an FBB::SharedSegment object. 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 the FBB::SharedSegment object, maintains a
table of, e.g., 10 entries, each 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 segments.
The class FBB::SharedSegment therefore defines a gateway, controlling
access to and allocating the shared memory data segment. The mentioned table
consists of nBlocks SharedBlock (sharedblock(3bobcat)) values,
offering mutexes and IDs of shared data segments. As always, the mutexes
control which process has access to a particular block of shared data memory,
and the IDs are either -1, meaning that their shared memory data segments has
as not yet been defined, or they contain the IDs of defined shared memory data
segments.
The class FBB::SharedSegment's sole responsibility is to offer the
framework as described. When used by a FBB::SharedMemory object different
processes may gain access to different parts of the shared memory data without
interfering each other's read and write actions.
NAMESPACE
FBB
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace FBB.
INHERITS FROM
-
CONSTRUCTORS
No publicly accessible constructors have been defined for
FBB::SharedSegment. A static member function create (see below) is
available, returning a pointer to a shared memory segment, in which a
FBB::SharedSegment has been defined.
OVERLOADED OPERATORS
std::ostream &operator<<(std::ostream &out,
SharedSegment const &sharedData):
The overloaded insertion operator inserts basic statistics of the
shared memory data into the ostream object. Information about the
IDs of the shared segments, their sizes, the maximum number of shared
data segments and the number of bytes that can be read from the shared
memory are displayed.
FBB::SharedBlock &operator[](size_t idx):
Table element idx of the table of FBB::SharedBlock
block IDs is returned. The behavior of the program is undefined if
idx is or exceeds nBlocks().
Overloaded move and copy assignment operators are not available.
MEMBER FUNCTIONS
size_t access() const:
The access rights of the shared memory segment are returned as a number
which is usually interpreted as an octal value, using the well-known
(chmod(1)) way to define the access rights for the owner, the
group and others.
void clear():
All the shared memory data blocks are unconditionally deleted and
nReadable returns 0 (the shared memory data blocks are not locked
prior to deleting them).
void lock(size_t idx) const:
Access to shared data segment idx is locked. This member itself
does not support recursive locking.
size_t nBlocks() const:
The number of shared memory data blocks that can be used by the
FBB::SharedSegment object is returned.
int newData(size_t idx):
The ID of a newly created shared memory data segment is returned. The
ID is also stored in the table of shared memory data segments that is
maintained by the FBB::SharedSegment object.
std::streamsize nReadable() const:
The number of characters (bytes) that can be read from the beginning of
the shared memory is returned.
void nReadableLock() const:
When returning from this member function a lock has been obtained of
FBB::SharedSegment's mutex controlling access the the object's
data member storing the number of characters that can be read from the
shared memory controlled by the FBB::SharedSegment object.
void nReadableUnlock() const:
This member function releases the lock previously acquired by
nReadableLock.
size_t segmentSize() const:
The size (in bytes) of the shared memory data blocks is returned. The
FBB::SharedSegment object can accomodate at most segmentSize() *
nBlocks() bytes.
void unlock(size_t idx) const:
Releases the lock on the shared memory data segment idx. If the
current process does not own the lock of shared memory data block
idx nothing happens and the function immediately returns.
void updateNreadable(std::streamsize offset):
The number of bytes that can be retrieved from the shared memory is
updated to max(nReadable(), offset).
STATIC MEMBER FUNCTIONS
void *attach(int id):
The address of shared memory segment id, mapped to the calling
process's memory area, is returned.
SharedSegment *create(int *id, size_t nBlocks, size_t segmentSize,
size_t access):
This member returns a pointer to a new FBB::SharedSegment object,
defined in the computer's shared memory, storing the shared memory's
ID at *id, and expecting the number of data blocks (nBlocks),
the size of these data blocks (segmentSize), and the shared
memory's access rights (access, using the well-known
(chmod(1)) way to define the access rights for the owner, the
group and others) as its arguments.
void deleteSegment(int id):
The shared memory segment having ID id is deleted from memory.
Type *detach(Type *sharedPtr, bool requireOK = true):
This member is defined as a member template. It expects a pointer to a
shared memory segment, previously mapped on the calling process's
memory space by attach, and detaches it from the process's memory
space, returning 0. By default, detaching the memory must succeed or a
FBB::Exception is thrown. Throwing an exception on failure can be
prevented by passing false as the member's second argument.
size_t size(int id):
The size (in bytes) of shared memory data block having ID id
is returned. An FBB::Exception is thrown if the size of segment
id cannot be determined.
EXAMPLE
See the sharedstream(3bobcat) man page.
FILES
bobcat/sharedsegment - defines the class interface