Provided by: libbobcat-dev_4.08.02-2build1_amd64 bug

NAME

       FBB::SharedMemory - Shared Memory memory structure

SYNOPSIS

       #include <bobcat/sharedmemory>
       Linking option: -lbobcat

DESCRIPTION

       The  class FBB::SharedMemory implements a usable interface to a shared memory segment made
       available by FBB::SharedSegment and monitored by FBB::SharedPos. It is the  main  building
       block  for  FBB::SharedStreambuf,  defining  the  `device’  to  which FBB::SharedStreambuf
       interfaces. All shared  memory  related  I/O  should  be  performed  by  FBB::SharedMemory
       objects, which are true objects, not themselves residing in shared memory.

       An  FBB::SharedMemory  object  defines,  connects  to and manages access to shared memory,
       encapsulating all raw shared memory operations. In addition to the class FBB::SharedMemory
       the  header  file  bobcat/sharedmemory  also  defines  a struct SharedEnum__ defining enum
       SizeUnit within the namespace FBB.

       The requested amount of shared memory is always a lower bound to  the  maximum  amount  of
       shared  memory  that  eventually may become available. When defining a SharedMemory object
       not all of its potentially available shared memory is immediately allocated. Shared memory
       will be allocated by the SharedMemory object once needed (up to a calculated maximum).

       As  a  fictitious  example:  assume 100 kB of memory is requested. The SharedMemory object
       then maintains a table of, e.g., 10 entries, each entry controlling  access  to  a  shared
       memory  block  of  10  kB.  These  10  kB  blocks aren’t immediately allocated, but become
       available once the program reads from or writes to addresses located in these data blocks.
       Newly allocated data blocks are initialized to 0-bytes.

       Caveat:  when constructing a shared memory segment make sure the segment’s ID is stored at
       a retrievable location. This allows other processes to  access  the  shared  segment.  The
       shared  segment  ID  is  also  required  to  delete a shared memory segment. If the shared
       segment ID is lost, the memory occupied by the shared memory segment remains  inaccessible
       (although  they  can  be  retrieved  and  removed  by  additional  means, like ipcs(1) and
       ipcrm(1)). The member id returns the ID of the shared memory  currently  monitored  by  an
       FBB::SharedMemory object.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       FBB::SharedEnum__

       The struct SharedEnum__ is a wrapper struct  around  enum  SizeUnit,  which  is  available
       through  inheritance  in  several  FBB::Shared*  classes,  and  offers  symbolic constants
       defining  standard  memory  sizes.  The  enum  SizeUnit  defines  the  following  symbolic
       constants:

       o      kB, representing 1024 (2**10) bytes of memory;

       o      MB, representing 1048576 (2**20) bytes of memory;

       o      GB, representing 1073741824 (2**30) bytes of memory

CONSTRUCTORS, DESTRUCTOR

       o      SharedMemory():
              The  default  constructor  defines an empty stub, which cannot immediately be used.
              As the SharedMemory class supports move  assignment,  empty  stubs  can  easily  be
              (re)configured at any time after their construction.

       o      SharedMemory(size_t maxSize, SizeUnit sizeUnit, size_t access = 0600):
              This  constructor  creates  a  shared  memory segment having a capacity of at least
              maxSize * sizeUnit bytes. The shared memory’s access  rights  are  defined  by  the
              access  parameter,  using  the  well-known (chmod(1)) octal values to define access
              rights for the owner, the group and others. If  construction  succeeds  the  shared
              memory is ready for use. If construction fails, an FBB::Exception is thrown.

       o      SharedMemory(int id):
              This  constructor connects to a shared memory segment having ID id. If construction
              succeeds the shared memory is ready for use. If construction fails (e.g., no shared
              memory segment having ID id exists), an FBB::Exception is thrown.

       o      ~SharedMemory():
              The   destructor   detaches   any   attached   shared   memory  segments  from  the
              FBB::SharedMemory object. If the shared memory segment is currently locked  by  the
              FBB::SharedMemory object, the lock is removed.

       copy and move constructors are not available.

OVERLOADED OPERATORS

       o      std::ostream &operator<<(std::ostream &out, SharedMemory const &sharedMemory):
              The overloaded insertion operator inserts information about the SharedMemory object
              into the provide ostream object. The IDs of the shared segments, their  sizes,  the
              maximum number of shared memory segments, the number of bytes that can be read from
              the shared memory, and its actual storage capacity, etc., are displayed.

       o      SharedMemory &operator=(SharedMemory &&rhs):
              The overloaded move assignment operator is available. It is used to (re)define  the
              shared memory segment an FBB::SharedMemory object is interfacing with.

       The overloaded copy assignment operator is not available.

MEMBER FUNCTIONS

       o      size_t blockOffset() const:
              The  offset  within the shared segment data block matching offset’s return value is
              returned. 0 is returned if the SharedMemory object has not yet been connected to  a
              shared memory block (or if the offset happens to be at the block’s offset 0).

       o      void clear():
              First,  the shared memory is locked. Next, all shared data segment are deleted, and
              the shared memory’s own  data  are  reset  to  indicate  it  is  completely  empty.
              Following  this  the  shared memory segment is unlocked again. Returning from clear
              the shared memory The FBB::SharedMemory object is effectively re-initialized,  with
              offset and nReadable returning 0.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      size_t dataSegmentSize() const:
              Returns the size (in bytes) of shared memory data  block.  0  is  returned  if  the
              SharedMemory object has not yet been connected to a shared memory block.

       o      int get():
              First  the  FBB::SharedMemory  object calls lock to lock the shared memory segment.
              Next the character at offset is retrieved and offset is incremented. Then unlock is
              called,  and  the  retrieved  character is returned. If offset is at least equal to
              nReadable, EOF is immediately returned.

              An FBB::Exception is thrown if the SharedMemory object has not yet  been  connected
              to a shared memory block.

       o      int id() const:
              The  ID  of  the  shared  memory segment is returned. Following kill id returns -1,
              indicating that the shared segment cannot be used anymore (note that operator=  can
              be used to re-initialize the FBB::SharedMemory object).

       o      SharedType *install(std::streamsize *offset, Params &&...params):
              This  member  was  implemented  as a member template, using typename SharedType and
              typename ...Params,  allowing  perfect  forwarding  of  arguments  to  SharedType’s
              constructor.

              This  member installs a SharedType object at SharedMemory’s at SharedMemory’s first
              available offset: either at the current offset, or (if SharedType’s size is too big
              to  fit  in  the  current  data  block  at  offset)  at  the first byte of the next
              SharedSegment shared data block.

              The actual offset where the SharedType object is installed is returned in  *offset,
              unless a nullptr is passed as install’s first argument.

              A  pointer to the installed SharedType is returned, with shmem.offset pointing just
              beyond SharedType’s last byte.

              The SharedType object is installed using placement new. E.g., the following example
              illustrates  how  a  SharedMutex(3bobcat)  object  can  be  installed  at the first
              possible location of SharedMemory shmem:

                  std::streamsize offset;
                  FBB::SharedMutex *mutexPtr = shmem.install<FBB::SharedMutex>(&offset);

              If the installed object must  be  destroyed,  its  destructor  must  explicitly  be
              called.    E.g.,    to   destroy   the   Mutex   pointed   at   by   mutexPtr   use
              mutexPtr->~SharedMutex().

              An FBB::Exception is thrown if shmem could not install the  object  in  its  shared
              memory data blocks.

       o      void kill():
              Without  locking the shared memory all shared memory controlled by the SharedMemory
              object is deleted. The SharedMemory object is unusable after returning  from  kill,
              with  its  id  member returns -1. Nothing happens if this member is called when the
              SharedMemory object has not yet been connected to a shared memory block.

       o      std::streamsize maxOffset() const:
              The maximum possible offset that can be used with  the  shared  memory  segment  is
              returned.  The  members  offset  and  nReadable  never exceed the value returned by
              maxOffset. 0 is returned if the SharedMemory object has not yet been connected to a
              shared memory block.

       o      std::streamsize nReadable() const:
              The  number of characters (bytes) that can be read from the beginning of the shared
              memory is returned. 0 is returned if the  SharedMemory  object  has  not  yet  been
              connected to a shared memory block.

       o      std::streamsize offset() const:
              The  offset  within  the  shared  memory  segment  (i.e., relative to the segment’s
              ios::beg position) is returned. 0 is returned if the SharedMemory  object  has  not
              yet  been connected to a shared memory block (or if the offset happens to be at the
              shared memory’s offset 0).

       o      char *ptr():
              Returns 0 if offset() ==  maxOffset().  Otherwise  it  returns  a  pointer  to  the
              character at index offset within the shared memory segment.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      int put(int ch):
              After locking the appropriate shared  data  segment,  ch  is  written  at  position
              offset, incrementing offset thereafter. If ch == EOF, EOF is immediately returned.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      int read(Type *value):
              This member was implemented as a member template. It calls the next member, casting
              Type  *  to  char  *, and using sizeof(Type) as its second argument.  The number of
              bytes actually read is returned. This member returns -1 if initially offset was  at
              least equal to nReadable.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      int read(char *data, std::streamsize len):
              While locking the appropriate shared data segment(s) at most  len  bytes  are  read
              from  the  shared memory, starting at offset. The bytes read from shared memory are
              stored at data.  The number of bytes actually read is returned. This member returns
              -1 if initially offset was at least equal to nReadable.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      int  read(std::ios::off_type  offset,  Type  *value,  std::ios::seekdir  origin   =
              std::ios::beg):
              This member was implemented as a member template. After changing the SharedMemory’s
              offset to offset (relative to origin), it calls the first read member,  passing  it
              value.  The  number  of  bytes actually read is returned. This member returns -1 if
              initially offset was at least equal to nReadable.

              An FBB::Exception is thrown if the SharedMemory object has not yet  been  connected
              to a shared memory block.

       o      void remove():
              The  shared  memory  is  locked,  after  which  all shared memory controlled by the
              FBB::SharedMemory object is deleted. The FBB::SharedMemory object is unusable after
              returning from remove.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      std::ios::pos_type  seek(std::ios::off_type  offset,  std::ios::seekdir  origin   =
              std::ios::beg):
              Moves  the  offset  position relative to way. The value -1 is returned when seeking
              before offset 0 or beyond maxOffset, otherwise the offset  relative  to  the  begin
              location  of the shared memory (i.e, offset for origin == ios::beg) is returned.  0
              is returned if the SharedMemory object has not  yet  been  connected  to  a  shared
              memory block (or if the offset happens to be at the shared memory’s offset 0).

       o      std::streamsize showmanyc() const:
              The  number  of  characters  that  can be read from the current shared segment data
              block is returned.  This member interrogates the number of readable  characters  in
              the  shared  memory  segment.  This  number  may  change while this member is being
              executed. In order to receive a stable return value, calling functions should  have
              obtained  a  lock  on  the  shared  memory segment before calling this member. 0 is
              returned if the SharedMemory object has not yet been connected to a  shared  memory
              block (or if the no characters can currently be read).

       o      void swap(SharedMemory &other):
              The current and other FBB::SharedMemory objects are swapped.

       o      bool truncate(std::streamsize offset):
              If  offset is not exceeding the value returned by nReadable nReadable is changed to
              offset and true is returned. Otherwise false is returned, and the value returned by
              nReadable is not changed.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      int write(Type const *value):
              This member was implemented as a member template. It calls the next member, casting
              Type  const  * to char const *, and using sizeof(Type) as its second argument.  The
              number of bytes actually written is returned. This member returns -1  if  initially
              offset was at least equal to maxOffset.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      int write(char const *data, std::streamsize len):
              The FBB::SharedMemory object calls lock to lock the shared memory,  and  writes  at
              most  len bytes into the shared memory, starting at offset. Next, unlock is called.
              The number of bytes actually written is returned. The member function returns -1 if
              initially offset is equal to maxOffset.

              An  FBB::Exception  is thrown if the SharedMemory object has not yet been connected
              to a shared memory block.

       o      int write(std::ios::off_type offset, Type const *value, std::ios::seekdir origin  =
              std::ios::beg):
              This member was implemented as a member template. After changing the SharedMemory’s
              offset to offset (relative to origin), it calls the first write member, passing  it
              value.  The number of bytes actually written is returned. This member returns -1 if
              initially offset was at least equal to maxOffset.

              An FBB::Exception is thrown if the SharedMemory object has not yet  been  connected
              to a shared memory block.

EXAMPLE

       See the sharedstream(3bobcat) man page.

FILES

       bobcat/sharedmemory - defines the class interface

SEE ALSO

       bobcat(7),  chmod(1),  ipcs(1),  ipcrm(1), isharedstream(3bobcat), osharedstream(3bobcat),
       sharedblock(3bobcat), sharedcondition(3bobcat), sharedmutex(3bobcat),  sharedpos(3bobcat),
       sharedreadme(7bobcat),            sharedsegment(3bobcat),           sharedstream(3bobcat),
       sharedstreambuf(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

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

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

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

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

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