Provided by: libbobcat-dev_6.04.00-1ubuntu3_amd64 
NAME
SharedREADME - Description of Bobcat’s shared memory classes
DESCRIPTION
The following shared memory classes are available:
o SharedBlock(3bobcat)
The class SharedBlock(3bobcat) defines a small object consisting of a SharedMutex and a (shared
segment) id. If offers functionality to set and retrieve the id, and to lock and unlock the
SharedMutex. SharedBlock objects are used by SharedSegment(3bobcat) objects to keep track of which
segments actually contain the shared memory data. It’s a bookkeeping helper class.
o SharedSegment(3bobcat)
The class SharedSegment (cf. figure images/sharedsegment1.jpg) interfaces to actual shared memory.
Its main member function is the static member create, returning a pointer to a newly allocated
SharedMemory object.
The member create receives as its input parameters the number of blocks, the size of the segments
allocated by SharedSegment, and the segment’s access mode (as used by, e.g., chmod(1)). It returns
a pointer to the allocated SharedSegment, and its ID (set using a pointer to an int, passed as its
first parameter).
Although the SharedSegment class defines an array of a single SharedBlock(3bobcat) object, in fact
it will contain d_nBlocks SharedBlock objects. The member create 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 SharedSegment constructor and placement new. Next, the remaining amount of raw shared
memory is initialized with d_nBlocks - 1 SharedBlock objects, again using placement new (cf.
figure images/sharedsegment2.jpg).
o SharedPos(3bobcat)
The class SharedPos(3bobcat) monitors position information in the shared memory segments managed
by SharedSegment objects. SharedPos only has a default constructor, but offers a reset member
receiving at construction time a pointer to a SharedSegment object.
o SharedMemory(3bobcat)
The class SharedMemory(3bobcat) offers the standard interface to shared memory, defining members
like read, get, write and put. It interfaces to a SharedSegment object, and uses a SharedPos
object to keep track of the SharedMemory’s offsets.
A SharedMemory object itself resides in a program’s working memory, and not in the computer’s
shared memory area. At any time the SharedMemory object only loads at most one actual block of the
shared memory block managed by SharedSegment. The current position in the shared memory managed by
SharedSegment is monitored by the SharedMemory’s SharedBlock d_pos member.
Following read/write operations the offset is updated accordingly. There’s only one offset, which
is used by [IO]?SharedStream objects when requesting or updating offsets. a SharedMemory 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 SharedMemory’s maximum possible offset.
o SharedMutex(3bobcat)
The class SharedMutex implements a non-recursive mutex that can be stored in shared memory. It
merely offers lock and unlock members. Within one thread lock should never be called repeatedly
unless unlock is called first. The unlock member may safely repeatedly be called; once the mutex
has been unlocked, repeated requests to unlock the mutex are simply ignored. When a SharedMutex is
destroyed it calls unlock. Use SharedMemory’s install member to define a SharedMutex object in
shared memory, and use ptr->~SharedMutex() (with SharedMutex *ptr pointing at the SharedMutex
object) to destroy it again.
o SharedCondition(3bobcat)
The class SharedCondition implements a condition variable and an associated mutex, both created in
shared memory controlled by a SharedMemory object. It offers all the functionality of
std::condition_variable. A SharedCondition object itself is defined in a thread’s working memory,
but interfaces to a `Condition’ object containing a condition variable and a mutex which are
installed in shared memory. The size of this `Condition’ object is returned by the static member
SharedCondition::size. SharedCondition members ensure that the thread has access to the
`Condition’ object, and that the shared memory’s offset has not changed when returning from the
SharedCondition’s members.
o SharedBuf(3bobcat)
The class SharedBuf implements a std::streambuf specialization interfacing to a SharedMemory
object. In addition to a default constructor which is an empty stub the class offers constructors
which immediately interface to a SharedMemory object, as well as a member to (re)associate a
SharedBuf object with a SharedMemory object.
o SharedStream, ISharedStream, OSharedStream(3bobcat)
These stream classes offer stream-facilities operating on shared memory maintained by a
SharedMemory object. The SharedStream class uses the SharedMemory’s seek member for both seekp and
seekg, and uses SharedMemory’s offset member for both tellp and tellg. All shared stream objects,
including ISharedStream, offer a member to initialize a SharedCondition
An overview of currently defined shared memory segments is shown by the command ipcs -ma. To
remove a defined shared memory segment the command ipcrm -m <id> can be used, where <id> is the
shared memory segment’s ID.
EXAMPLE
See the sharedstream(3bobcat) man page.
FILES
Images referred to in this man-page are located in the source distribution in bobcat/documents/images, or
they can be found in the standard location of documentation files in your distribution (e.g., they are
located in /usr/share/doc/libbobcat6/images).
SEE ALSO
bobcat(7), ipcs(1), ipcrm(1), isharedstream(3bobcat), osharedstream(3bobcat), sharedblock(3bobcat),
sharedcondition(3bobcat), sharedmemory(3bobcat), sharedmutex(3bobcat), sharedpos(3bobcat),
sharedsegment(3bobcat), sharedstream(3bobcat), sharedbuf(3bobcat)
BUGS
None Reported.
BOBCAT PROJECT FILES
o https://fbb-git.gitlab.io/bobcat/: gitlab project page;
o bobcat_6.04.00-x.dsc: detached signature;
o bobcat_6.04.00-x.tar.gz: source archive;
o bobcat_6.04.00-x_i386.changes: change log;
o libbobcat1_6.04.00-x_*.deb: debian package containing the libraries;
o libbobcat1-dev_6.04.00-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).