trusty (3) sharedsegment.3bobcat.gz
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).