Provided by: libbobcat-dev_5.00.02-2_amd64 bug

NAME

       SharedREADME - Description of Bobcat’s shared memory classes

DESCRIPTION

       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      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/libbobcat5/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.

DISTRIBUTION FILES

       o      bobcat_5.00.02-x.dsc: detached signature;

       o      bobcat_5.00.02-x.tar.gz: source archive;

       o      bobcat_5.00.02-x_i386.changes: change log;

       o      libbobcat1_5.00.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.00.02-x_*.deb: debian package holding the libraries,  headers  and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

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).