Provided by: libbobcat-dev_3.19.01-1ubuntu1_amd64 
NAME
FBB::SharedSegment - Shared Memory data structure
SYNOPSIS
#include <bobcat/sharedsegment>
Linking option: -lbobcat
DESCRIPTION
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
o 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.
o 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
o 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.
o 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).
o void lock(size_t idx) const:
Access to shared data segment idx is locked. This member itself does not support
recursive locking.
o size_t nBlocks() const:
The number of shared memory data blocks that can be used by the FBB::SharedSegment
object is returned.
o 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.
o std::streamsize nReadable() const:
The number of characters (bytes) that can be read from the beginning of the shared
memory is returned.
o 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.
o void nReadableUnlock() const:
This member function releases the lock previously acquired by nReadableLock.
o 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.
o 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.
o 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
o void *attach(int id):
The address of shared memory segment id, mapped to the calling process’s memory
area, is returned.
o 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.
o void deleteSegment(int id):
The shared memory segment having ID id is deleted from memory.
o 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.
o 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
SEE ALSO
bobcat(7), chmod(1), isharedstream(3bobcat), osharedstream(3bobcat), sharedblock(3bobcat),
sharedmemory(3bobcat), sharedmutex(3bobcat), sharedpos(3bobcat), sharedstream(3bobcat),
sharedstreambuf(3bobcat)
BUGS
None Reported.
DISTRIBUTION FILES
o bobcat_3.19.01-x.dsc: detached signature;
o bobcat_3.19.01-x.tar.gz: source archive;
o bobcat_3.19.01-x_i386.changes: change log;
o libbobcat1_3.19.01-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_3.19.01-x_*.deb: debian package holding the libraries, headers and
manual pages;
o http://sourceforge.net/projects/bobcat: public archive location;
BOBCAT
Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License
(GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl).