SharedREADME - Description of Bobcat’s shared memory
classes
- o
- SharedLock(3bobcat)
- The class SharedLock(3bobcat) is a wrapper around a
pthread_mutex. SharedLock has member functions lock
and unlock, with lock throwing an exception when it fails to
obtain the lock (i.e., calling pthread_mutex’s lock member
fails, otherwise it waits until pthread_mutex’s lock
succeeds).
- SharedLock is a convenience class for other shared memory classes.
By itself SharedLock is unrelated to shared memory.
- 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 lcok 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
- SharedStreambuf(3bobcat)
- The class SharedStreambuf 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 SharedStreambuf 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.
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/libbobcat4/images).
bobcat(7), ipcs(1), ipcrm(1),
isharedstream(3bobcat), osharedstream(3bobcat),
sharedblock(3bobcat), sharedcondition(3bobcat),
sharedmemory(3bobcat), sharedmutex(3bobcat),
sharedpos(3bobcat), sharedsegment(3bobcat),
sharedstream(3bobcat), sharedstreambuf(3bobcat)
- o
- bobcat_4.08.06-x.dsc: detached signature;
- o
- bobcat_4.08.06-x.tar.gz: source archive;
- o
- bobcat_4.08.06-x_i386.changes: change log;
- o
- libbobcat1_4.08.06-x_*.deb: debian package holding the
libraries;
- o
- libbobcat1-dev_4.08.06-x_*.deb: debian package holding the
libraries, headers and manual pages;
- o
- http://sourceforge.net/projects/bobcat: public archive location;
Bobcat is an acronym of `Brokken’s Own Base Classes And
Templates’.
This is free software, distributed under the terms of the GNU
General Public License (GPL).
Frank B. Brokken (f.b.brokken@rug.nl).