.TH "FBB::SharedSegment" "3bobcat" "2005\-2020" "libbobcat\-dev_5\&.07\&.00" "Shared Memory Data"

.PP 
.SH "NAME"
FBB::SharedSegment \- Shared Memory data structure
.PP 
.SH "SYNOPSIS"
\fB#include <bobcat/sharedsegment>\fP
.br 
Linking option: \fI\-lbobcat \fP 
.PP 
.SH "DESCRIPTION"

.PP 
The class \fBFBB::SharedSegment\fP implements the shared memory data
structure used by Bobcat\(cq\&s shared memory classes\&. Bobcat\(cq\&s
\fISharedMemory\fP class accesses or defines a shared memory segment,
controlling all its read and write operations\&. 
.PP 
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
\fBSharedSegment\fP object not all of its potentially available shared memory is
immediately allocated\&. Shared memory will be allocated by the
\fBSharedSegment\fP object once needed (up to a calculated maximum)\&.
.PP 
As a fictitious example: assume 100 kB of memory is requested, then the
\fBSharedSegment\fP 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\(cq\&t immediately allocated, but become available once the program reads from
or writes to addresses located in these data segments\&.
.PP 
The class \fBSharedSegment\fP therefore defines a gateway, controlling access to
and allocating required shared memory data segments\&. The mentioned table
consists of \fInBlocks SharedBlock\fP (\fBsharedblock\fP(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\&.
.PP 
The class \fBSharedSegment\fP\(cq\&s sole responsibility is to offer the
framework as described\&. When used by a \fIFBB::SharedMemory\fP object different
processes may gain access to different parts of the shared memory data without
interfering each other\(cq\&s read and write actions\&.
.PP 
.SH "NAMESPACE"
\fBFBB\fP
.br 
All constructors, members, operators and manipulators, mentioned in this
man\-page, are defined in the namespace \fBFBB\fP\&.
.PP 
.SH "INHERITS FROM"
\-
.PP 
.SH "CONSTRUCTORS"

.PP 
No publicly accessible constructors have been defined for
\fBSharedSegment\fP\&. A static member function \fIcreate\fP (see below) is
available, returning a pointer to a shared memory segment, in which a
\fBSharedSegment\fP has been defined\&.
.PP 
.SH "OVERLOADED OPERATORS"
.IP o 
\fBstd::ostream &operator<<(std::ostream &out, 
SharedSegment const &sharedData)\fP:
.br 
The overloaded insertion operator inserts basic statistics of the
shared memory data into the \fIostream\fP 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\&.
.IP 
.IP o 
\fBFBB::SharedBlock &operator[](size_t idx)\fP:
.br 
Table element \fIidx\fP of the table of \fIFBB::SharedBlock\fP
block IDs is returned\&. The behavior of the program is undefined if
\fIidx\fP is or exceeds \fInBlocks()\fP\&.
.IP 
Copy and move constructors (and assignment operators) are not available\&.
.PP 
.SH "MEMBER FUNCTIONS"
.IP o 
\fBsize_t access() const\fP:
.br 
Returns the access rights of the shared memory segment as a number
which is usually interpreted as an octal value, using the well\-known
(\fBchmod\fP(1)) way to define the access rights for owner, group and
others\&.
.IP 
.IP o 
\fBvoid clear()\fP:
.br 
All the shared memory data blocks are unconditionally deleted and
\fInReadable\fP returns 0 (the shared memory data blocks are not locked
prior to deleting them)\&. After calling \fIclear\fP all allocated 
\fBSharedSegment\fP\(cq\&s shared memory segments have ceased to exist and
can no longer be used\&.
.IP 
.IP o 
\fBvoid lock(size_t idx) const\fP:
.br 
Access to shared data segment \fIidx\fP is locked\&. This member itself
does not support recursive locking\&.
.IP 
.IP o 
\fBsize_t nBlocks() const\fP:
.br 
Returns the number of shared memory data blocks that can be used by the
\fBFBB::SharedSegment\fP object\&.
.IP 
.IP o 
\fBint newData(size_t idx)\fP:
.br 
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 \fBSharedSegment\fP object\&.
.IP 
An \fIFBB::Exception\fP is thrown if the shared memory data segment
could not be allocated\&.
.IP 
.IP o 
\fBstd::streamsize nReadable() const\fP:
.br 
Returns the number of characters (bytes) that can be read from the
beginning of the shared memory\&.
.IP 
.IP o 
\fBvoid nReadableLock() const\fP:
.br 
When returning from this member function a lock has been obtained of
\fBSharedSegment\fP\(cq\&s mutex controlling access the the object\(cq\&s
data member storing the number of characters that can be read from the
shared memory controlled by the \fBSharedSegment\fP object\&.
.IP 
.IP o 
\fBvoid nReadableUnlock() const\fP:
.br 
This member function releases the lock previously acquired by
\fInReadableLock\fP\&.
.IP 
.IP o 
\fBsize_t segmentSize() const\fP:
.br 
Returns the size (in bytes) of the shared memory data blocks\&. The
\fBSharedSegment\fP object can accommodate at most \fIsegmentSize() *
nBlocks()\fP bytes\&.
.IP 
.IP o 
\fBbool truncate(std::streamsize offset)\fP:
.br 
After calling \fInReadableLock\fP, if \fIoffset\fP is not exceeding the
value returned by \fInReadable\fP \fInReadable\fP is changed to \fIoffset\fP
and \fItrue\fP is returned\&. Otherwise \fIfalse\fP is returned, and the
value returned by \fInReadable\fP has not been changed\&. Before returning
\fInReadableUnlock\fP is called\&.
.IP 
.IP o 
\fBvoid unlock(size_t idx) const\fP:
.br 
Releases the lock on the shared memory data segment \fIidx\fP\&. If the
current process does not own the lock of shared memory data block
\fIidx\fP nothing happens and the function immediately returns\&.
.IP 
.IP o 
\fBvoid updateNreadable(std::streamsize offset)\fP:
.br 
The number of bytes that can be retrieved from the shared memory is
updated to \fImax(nReadable(), offset)\fP\&. 

.PP 
.SH "STATIC MEMBER FUNCTIONS"

.PP 
.IP o 
\fBvoid *attach(int id)\fP:
.br 
Returns the address of shared memory segment \fIid\fP, mapped to the
calling process\(cq\&s memory area\&.
.IP 
An \fIFBB::Exception\fP is thrown if the shared memory data segment
could not be attached\&.
.IP 
.IP o 
\fBSharedSegment *create(int *id, size_t nBlocks, size_t segmentSize, 
size_t access)\fP:
.br 
Returns a pointer to a newly created  \fBSharedSegment\fP object,
defined in the computer\(cq\&s shared memory\&. 
.IP 
The created shared memory\(cq\&s ID is stored at \fI*id\fP\&. The remaining
arguments define the potential number of shared memory data blocks
(\fInBlocks\fP); the size of these data blocks (\fIsegmentSize\fP); and
the shared memory\(cq\&s access rights (\fIaccess\fP, using the well\-known
octal value representation as used by (\fBchmod\fP(1)) to define access
rights for the owner, the group and others)\&.
.IP 
An \fIFBB::Exception\fP is thrown if the shared memory data segment
could not be created\&.
.IP 
.IP o 
\fBvoid deleteSegment(int id)\fP:
.br 
The shared memory segment having ID \fIid\fP is deleted\&. After calling
\fIdeleteSegment\fP shared memory segment \fIid\fP doesn\(cq\&t exist
anymore\&. The \fIid\fP can be the shared memory ID of any segment for
which the current user has write permissions\&.
.IP 
An \fIFBB::Exception\fP is thrown if shared memory data segment \fIid\fP
could not be deleted\&.
.IP 
.IP o 
\fBType *detach(Type *sharedPtr, bool requireOK = true)\fP:
.br 
This member is defined as a member template\&. It expects a pointer to a
shared memory segment, previously mapped on the calling process\(cq\&s
memory space by \fIattach\fP, and detaches it from the process\(cq\&s memory
space, returning 0\&. 
.IP 
By default, detaching the memory must succeed or an \fBFBB::Exception\fP
is thrown\&. Throwing an exception on failure can be prevented by
passing \fIfalse\fP as the member\(cq\&s second argument\&.
.IP 
.IP o 
\fBsize_t size(int id)\fP:
.br 
The size (in bytes) of shared memory data block having ID \fIid\fP is
returned\&.
.IP 
An \fIFBB::Exception\fP is thrown if the size of segment \fIid\fP could
not be determined\&.

.PP 
.SH "EXAMPLE"
See the \fBsharedstream\fP(3bobcat) man page\&.
.PP 
.SH "FILES"
\fIbobcat/sharedsegment\fP \- defines the class interface
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBchmod\fP(1),
\fBisharedstream\fP(3bobcat),
\fBosharedstream\fP(3bobcat),
\fBsharedblock\fP(3bobcat),
\fBsharedcondition\fP(3bobcat), 
\fBsharedmemory\fP(3bobcat),
\fBsharedmutex\fP(3bobcat), 
\fBsharedpos\fP(3bobcat), 
\fBsharedreadme\fP(7bobcat), 
\fBsharedstream\fP(3bobcat), 
\fBsharedbuf\fP(3bobcat)
.PP 
.SH "BUGS"
None Reported\&.
.PP 
.SH "BOBCAT PROJECT FILES"

.PP 
.IP o 
\fIhttps://fbb\-git\&.gitlab\&.io/bobcat/\fP: gitlab project page;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_5\&.07\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_5\&.07\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_5\&.07\&.00\-x_*\&.deb\fP: debian package containing the
libraries, headers and manual pages;

.PP 
.SH "BOBCAT"
Bobcat is an acronym of `Brokken\(cq\&s Own Base Classes And Templates\(cq\&\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP