xenial (7) sharedreadme.7bobcat.gz

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

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/libbobcat4/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), sharedstreambuf(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_4.01.03-x.dsc: detached signature;

       o      bobcat_4.01.03-x.tar.gz: source archive;

       o      bobcat_4.01.03-x_i386.changes: change log;

       o      libbobcat1_4.01.03-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_4.01.03-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).