Provided by: libbobcat-dev_6.03.02-2_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 used by Bobcat’s
shared memory classes. Bobcat’s SharedMemory class accesses or defines a shared memory
segment, controlling all its read and write operations.
The requested amount of shared memory is always a lower bound to the maximum amount of
shared memory that eventually may become available. When defining a SharedSegment object
not all of its potentially available shared memory is immediately allocated. Shared memory
will be allocated by the SharedSegment object once needed (up to a calculated maximum).
As a fictitious example: assume 100 kB of memory is requested, then the 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 SharedSegment therefore defines a gateway, controlling access to and allocating
required shared memory data segments. The mentioned table consists of nBlocks SharedBlock
(sharedblock(3bobcat)) values, offering mutexes and IDs of shared data segments. 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
allocated, or they contain the IDs of defined shared memory data segments.
The class 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 SharedSegment. A static member
function create (see below) is available, returning a pointer to a shared memory segment,
in which a 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().
Copy and move constructors (and assignment operators) are not available.
MEMBER FUNCTIONS
o size_t access() const:
Returns the access rights of the shared memory segment as a number which is usually
interpreted as an octal value, using the well-known (chmod(1)) way to define the
access rights for owner, 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). After
calling clear all allocated SharedSegment’s shared memory segments have ceased to
exist and can no longer be used.
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:
Returns the number of shared memory data blocks that can be used by the
FBB::SharedSegment object.
o int newData(size_t idx):
Returns the ID of a newly created shared memory data segment. The ID is also stored
in the table of shared memory data segments that is maintained by the SharedSegment
object.
An FBB::Exception is thrown if the shared memory data segment could not be
allocated.
o std::streamsize nReadable() const:
Returns the number of characters (bytes) that can be read from the beginning of the
shared memory.
o void nReadableLock() const:
When returning from this member function a lock has been obtained of
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
SharedSegment object.
o void nReadableUnlock() const:
This member function releases the lock previously acquired by nReadableLock.
o size_t segmentSize() const:
Returns the size (in bytes) of the shared memory data blocks. The SharedSegment
object can accommodate at most segmentSize() * nBlocks() bytes.
o bool truncate(std::streamsize offset):
After calling nReadableLock, if offset is not exceeding the value returned by
nReadable nReadable is changed to offset and true is returned. Otherwise false is
returned, and the value returned by nReadable has not been changed. Before
returning nReadableUnlock is called.
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):
Returns the address of shared memory segment id, mapped to the calling process’s
memory area.
An FBB::Exception is thrown if the shared memory data segment could not be
attached.
o SharedSegment *create(int *id, size_t nBlocks, size_t segmentSize, size_t access):
Returns a pointer to a newly created SharedSegment object, defined in the
computer’s shared memory.
The created shared memory’s ID is stored at *id. The remaining arguments define the
potential number of shared memory data blocks (nBlocks); the size of these data
blocks (segmentSize); and the shared memory’s access rights (access, using the
well-known octal value representation as used by (chmod(1)) to define access rights
for the owner, the group and others).
To return the shared segment to the operating system deleteSegment should be used.
An FBB::Exception is thrown if the shared memory data segment could not be created.
o void deleteSegment(int id):
The shared memory segment having ID id is deleted. After calling deleteSegment
shared memory segment id doesn’t exist anymore. The id can be the shared memory ID
of any segment for which the current user has write permissions.
An FBB::Exception is thrown if shared memory data segment id could not be deleted.
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 an FBB::Exception is thrown.
Throwing an exception on failure can be prevented by passing false as the member’s
second argument.
Note that detaching a memory segment does not destroy it. To return a shared
segment to the operating system deleteSegment should be used.
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 could not 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),
sharedcondition(3bobcat), sharedmemory(3bobcat), sharedmutex(3bobcat), sharedpos(3bobcat),
sharedreadme(7bobcat), sharedstream(3bobcat), sharedbuf(3bobcat)
BUGS
None Reported.
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_6.03.02-x.dsc: detached signature;
o bobcat_6.03.02-x.tar.gz: source archive;
o bobcat_6.03.02-x_i386.changes: change log;
o libbobcat1_6.03.02-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_6.03.02-x_*.deb: debian package containing the libraries, headers
and manual pages;
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).