.TH "SharedREADME" "7bobcat" "2005\-2023" "libbobcat\-dev_6\&.04\&.00" "Bobcat Shared Memory README"

.PP 
.SH "NAME"
SharedREADME \- Description of Bobcat\(cq\&s shared memory classes
.PP 
.SH "DESCRIPTION"

.PP 
The following shared memory classes are available:
.PP 
.IP o 
\fBSharedBlock\fP(3bobcat)
.IP 
The class \fBSharedBlock\fP(3bobcat) defines a small object consisting of a
\fBSharedMutex\fP and a (shared segment) id\&. If offers functionality to set and
retrieve the id, and to lock and unlock the \fBSharedMutex\fP\&. \fBSharedBlock\fP
objects are used by
\fBSharedSegment\fP(3bobcat) objects to keep track of which segments actually
contain the shared memory data\&. It\(cq\&s a bookkeeping helper class\&.
.IP 
.IP o 
\fBSharedSegment\fP(3bobcat)
.IP 
The class \fBSharedSegment\fP (cf\&. figure \fIimages/sharedsegment1\&.jpg\fP)
interfaces to actual shared memory\&. Its main member function is the static
member \fIcreate\fP, returning a pointer to a newly allocated \fISharedMemory\fP
object\&.
.IP 
The member \fIcreate\fP receives as its input parameters the number of blocks,
the size of the segments allocated by \fBSharedSegment\fP, and the segment\(cq\&s
access mode (as used by, e\&.g\&., \fBchmod\fP(1))\&. It returns a pointer to the
allocated \fISharedSegment\fP, and its ID (set using a pointer to an \fIint\fP,
passed as its first parameter)\&.
.IP 
Although the \fBSharedSegment\fP class defines an array of a single
\fBSharedBlock\fP(3bobcat) object, in fact it will contain \fId_nBlocks\fP
\fBSharedBlock\fP objects\&. The member \fIcreate\fP first allocates a block of raw
memory of the required total size\&. Next it initializes the first part of this
raw, shared memory, using the \fISharedSegment\fP constructor and placement
new\&. Next, the remaining amount of raw shared memory is initialized with
\fId_nBlocks \- 1\fP \fBSharedBlock\fP objects, again using placement new
(cf\&. figure \fIimages/sharedsegment2\&.jpg\fP)\&.
.IP o 
\fBSharedPos\fP(3bobcat)
.IP 
The class \fBSharedPos\fP(3bobcat) monitors position information in the shared
memory segments managed by \fBSharedSegment\fP objects\&. \fBSharedPos\fP only has a
default constructor, but offers a \fBreset\fP member receiving at construction
time a pointer to a \fBSharedSegment\fP object\&.
.IP 
.IP o 
\fBSharedMemory\fP(3bobcat)
.IP 
The class \fBSharedMemory\fP(3bobcat) offers the standard interface to
shared memory, defining members like \fIread, get, write\fP and \fIput\fP\&. It
interfaces to a \fISharedSegment\fP object, and uses a \fISharedPos\fP object to
keep track of the \fISharedMemory\(cq\&s\fP offsets\&.
.IP 
A \fBSharedMemory\fP object itself resides in a program\(cq\&s working memory, and not
in the computer\(cq\&s shared memory area\&. At any time the \fBSharedMemory\fP object
only loads at most one actual block of the shared memory block managed by
\fBSharedSegment\fP\&. The current position in the shared memory managed by
\fBSharedSegment\fP is monitored by the \fBSharedMemory\fP\(cq\&s \fISharedBlock d_pos\fP
member\&.
.IP 
Following read/write operations the offset is updated accordingly\&. There\(cq\&s
only one offset, which is used by \fI[IO]?SharedStream\fP objects when
requesting or updating offsets\&. a \fBSharedMemory\fP object offers safeguards
against inappropriate use\&. E\&.g\&., if no memory has been allocated yet it may
thow exceptions\&. Also, offsets can never exceed the \fISharedMemory\(cq\&s\fP maximum
possible offset\&.
.IP 
.IP o 
\fBSharedMutex\fP(3bobcat)
.IP 
The class \fBSharedMutex\fP implements a non\-recursive mutex that can be stored
in shared memory\&. It merely offers \fIlock\fP and \fIunlock\fP members\&. Within one
thread \fIlock\fP should never be called repeatedly unless \fIunlock\fP is called
first\&. The \fIunlock\fP member may safely repeatedly be called; once the mutex
has been unlocked, repeated requests to unlock the mutex are simply
ignored\&. When a \fBSharedMutex\fP is destroyed it calls \fIunlock\fP\&. Use
\fISharedMemory\(cq\&s install\fP member to define a \fBSharedMutex\fP object in shared
memory, and use \fIptr\->~SharedMutex()\fP (with \fISharedMutex *ptr\fP pointing at
the \fISharedMutex\fP object) to destroy it again\&.
.IP 
.IP o 
\fBSharedCondition\fP(3bobcat)
.IP 
The class \fBSharedCondition\fP implements a condition variable and an
associated mutex, both created in shared memory controlled by a
\fBSharedMemory\fP object\&. It offers all the functionality of
\fIstd::condition_variable\fP\&. A \fBSharedCondition\fP object itself is defined in
a thread\(cq\&s working memory, but interfaces to a \fI`Condition\(cq\&\fP object
containing a condition variable and a mutex which are installed in shared
memory\&. The size of this \fI`Condition\(cq\&\fP object is returned by the static
member \fISharedCondition::size\fP\&. \fBSharedCondition\fP members ensure that the
thread has access to the \fI`Condition\(cq\&\fP object, and that the shared memory\(cq\&s
offset has not changed when returning from the \fBSharedCondition\(cq\&s\fP members\&.
.IP 
.IP o 
\fBSharedBuf\fP(3bobcat)
.IP 
The class \fBSharedBuf\fP implements a \fIstd::streambuf\fP specialization
interfacing to a \fISharedMemory\fP object\&. In addition to a default constructor
which is an empty stub the class offers constructors which immediately
interface to a \fISharedMemory\fP object, as well as a member to (re)associate
a \fBSharedBuf\fP object with a \fISharedMemory\fP object\&.
.IP 
.IP o 
\fBSharedStream, ISharedStream, OSharedStream\fP(3bobcat)
.IP 
These stream classes offer stream\-facilities operating on shared memory
maintained by a \fISharedMemory\fP object\&. The \fBSharedStream\fP class uses the
\fISharedMemory\(cq\&s seek\fP member for both \fIseekp\fP and \fIseekg\fP, and uses
\fISharedMemory\(cq\&s offset\fP member for both \fItellp\fP and \fItellg\fP\&. All shared
stream objects, including \fBISharedStream\fP, offer a member to initialize a
\fISharedCondition\fP
.IP 
An overview of currently defined shared memory segments is shown by the
command \fIipcs \-ma\fP\&. To remove a defined shared memory segment the command
\fIipcrm \-m <id>\fP can be used, where \fI<id>\fP is the shared memory segment\(cq\&s
ID\&.
.PP 
.SH "EXAMPLE"
See the \fBsharedstream\fP(3bobcat) man page\&.
.PP 
.SH "FILES"

.PP 
Images referred to in this man\-page are located in the source distribution
in \fIbobcat/documents/images\fP, or they can be found in the standard location
of documentation files in your distribution (e\&.g\&., they are located in
\fI/usr/share/doc/libbobcat6/images\fP)\&.
.PP 
.SH "SEE ALSO"
\fBbobcat\fP(7), \fBipcs\fP(1), \fBipcrm\fP(1),
\fBisharedstream\fP(3bobcat),
\fBosharedstream\fP(3bobcat),
\fBsharedblock\fP(3bobcat),
\fBsharedcondition\fP(3bobcat),
\fBsharedmemory\fP(3bobcat),
\fBsharedmutex\fP(3bobcat),
\fBsharedpos\fP(3bobcat),
\fBsharedsegment\fP(3bobcat),
\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_6\&.04\&.00\-x\&.dsc\fP: detached signature;
.IP o 
\fIbobcat_6\&.04\&.00\-x\&.tar\&.gz\fP: source archive;
.IP o 
\fIbobcat_6\&.04\&.00\-x_i386\&.changes\fP: change log;
.IP o 
\fIlibbobcat1_6\&.04\&.00\-x_*\&.deb\fP: debian package containing the
libraries;
.IP o 
\fIlibbobcat1\-dev_6\&.04\&.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