Provided by: libbobcat-dev_6.03.02-2_amd64 bug

NAME

       FBB::SharedSegment - Shared Memory data structure

SYNOPSIS

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

DESCRIPTION

       The  class FBB::SharedSegment implements the shared memory data structure used by Bobcat’s
       shared memory classes. Bobcat’s SharedMemory class accesses or  defines  a  shared  memory
       segment, controlling all its read and write operations.

       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  SharedSegment  object
       not all of its potentially available shared memory is immediately allocated. Shared memory
       will be allocated by the SharedSegment object once needed (up to a calculated maximum).

       As a fictitious example: assume 100 kB of memory  is  requested,  then  the  SharedSegment
       object,  maintains  a  table of, e.g., 10 entries, each controlling the 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
       segments.

       The class SharedSegment therefore defines a gateway, controlling access to and  allocating
       required  shared memory data segments. The mentioned table consists of nBlocks SharedBlock
       (sharedblock(3bobcat)) values, offering mutexes and  IDs  of  shared  data  segments.  The
       mutexes  control which process has access to a particular block of shared data memory, and
       the IDs are either -1, meaning that their shared memory data segments has as not yet  been
       allocated, or they contain the IDs of defined shared memory data segments.

       The class SharedSegment’s sole responsibility is to offer the framework as described. When
       used by a FBB::SharedMemory object different processes may gain access to different  parts
       of the shared memory data without interfering each other’s read and write actions.

NAMESPACE

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

INHERITS FROM

       -

CONSTRUCTORS

       No publicly accessible constructors have been defined for SharedSegment. A  static  member
       function  create (see below) is available, returning a pointer to a shared memory segment,
       in which a SharedSegment has been defined.

OVERLOADED OPERATORS

       o      std::ostream &operator<<(std::ostream &out, SharedSegment const &sharedData):
              The overloaded insertion operator inserts basic statistics  of  the  shared  memory
              data  into  the  ostream  object. Information about the IDs of the shared segments,
              their sizes, the maximum number of shared data segments and  the  number  of  bytes
              that can be read from the shared memory are displayed.

       o      FBB::SharedBlock &operator[](size_t idx):
              Table  element  idx  of  the  table  of FBB::SharedBlock block IDs is returned. The
              behavior of the program is undefined if idx is or exceeds nBlocks().

              Copy and move constructors (and assignment operators) are not available.

MEMBER FUNCTIONS

       o      size_t access() const:
              Returns the access rights of the shared memory segment as a number which is usually
              interpreted  as  an  octal value, using the well-known (chmod(1)) way to define the
              access rights for owner, group and others.

       o      void clear():
              All the shared memory data blocks are unconditionally deleted and nReadable returns
              0  (the  shared  memory  data  blocks are not locked prior to deleting them). After
              calling clear all allocated SharedSegment’s shared memory segments have  ceased  to
              exist and can no longer be used.

       o      void lock(size_t idx) const:
              Access  to  shared  data segment idx is locked. This member itself does not support
              recursive locking.

       o      size_t nBlocks() const:
              Returns the  number  of  shared  memory  data  blocks  that  can  be  used  by  the
              FBB::SharedSegment object.

       o      int newData(size_t idx):
              Returns the ID of a newly created shared memory data segment. The ID is also stored
              in the table of shared memory data segments that is maintained by the SharedSegment
              object.

              An  FBB::Exception  is  thrown  if  the  shared  memory  data  segment could not be
              allocated.

       o      std::streamsize nReadable() const:
              Returns the number of characters (bytes) that can be read from the beginning of the
              shared memory.

       o      void nReadableLock() const:
              When   returning   from   this   member  function  a  lock  has  been  obtained  of
              SharedSegment’s mutex controlling access the the object’s data member  storing  the
              number  of  characters  that  can  be read from the shared memory controlled by the
              SharedSegment object.

       o      void nReadableUnlock() const:
              This member function releases the lock previously acquired by nReadableLock.

       o      size_t segmentSize() const:
              Returns the size (in bytes) of the shared memory  data  blocks.  The  SharedSegment
              object can accommodate at most segmentSize() * nBlocks() bytes.

       o      bool truncate(std::streamsize offset):
              After  calling  nReadableLock,  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  has  not  been changed. Before
              returning nReadableUnlock is called.

       o      void unlock(size_t idx) const:
              Releases the lock on the shared memory data segment idx.  If  the  current  process
              does  not  own  the  lock  of  shared memory data block idx nothing happens and the
              function immediately returns.

       o      void updateNreadable(std::streamsize offset):
              The number of bytes that can be retrieved from the  shared  memory  is  updated  to
              max(nReadable(), offset).

STATIC MEMBER FUNCTIONS

       o      void *attach(int id):
              Returns  the  address  of shared memory segment id, mapped to the calling process’s
              memory area.

              An FBB::Exception is thrown  if  the  shared  memory  data  segment  could  not  be
              attached.

       o      SharedSegment *create(int *id, size_t nBlocks, size_t segmentSize, size_t access):
              Returns  a  pointer  to  a  newly  created   SharedSegment  object,  defined in the
              computer’s shared memory.

              The created shared memory’s ID is stored at *id. The remaining arguments define the
              potential  number  of  shared  memory data blocks (nBlocks); the size of these data
              blocks (segmentSize); and the shared memory’s  access  rights  (access,  using  the
              well-known octal value representation as used by (chmod(1)) to define access rights
              for the owner, the group and others).

              To return the shared segment to the operating system deleteSegment should be used.

              An FBB::Exception is thrown if the shared memory data segment could not be created.

       o      void deleteSegment(int id):
              The shared memory segment having ID id  is  deleted.  After  calling  deleteSegment
              shared  memory segment id doesn’t exist anymore. The id can be the shared memory ID
              of any segment for which the current user has write permissions.

              An FBB::Exception is thrown if shared memory data segment id could not be deleted.

       o      Type *detach(Type *sharedPtr, bool requireOK = true):
              This member is defined as a member template. It  expects  a  pointer  to  a  shared
              memory  segment, previously mapped on the calling process’s memory space by attach,
              and detaches it from the process’s memory space, returning 0.

              By default, detaching the memory must  succeed  or  an  FBB::Exception  is  thrown.
              Throwing  an exception on failure can be prevented by passing false as the member’s
              second argument.

              Note that detaching a memory segment does  not  destroy  it.  To  return  a  shared
              segment to the operating system deleteSegment should be used.

       o      size_t size(int id):
              The size (in bytes) of shared memory data block having ID id is returned.

              An FBB::Exception is thrown if the size of segment id could not be determined.

EXAMPLE

       See the sharedstream(3bobcat) man page.

FILES

       bobcat/sharedsegment - defines the class interface

SEE ALSO

       bobcat(7), chmod(1), isharedstream(3bobcat), osharedstream(3bobcat), sharedblock(3bobcat),
       sharedcondition(3bobcat), sharedmemory(3bobcat), sharedmutex(3bobcat), sharedpos(3bobcat),
       sharedreadme(7bobcat), sharedstream(3bobcat), sharedbuf(3bobcat)

BUGS

       None Reported.

BOBCAT PROJECT FILES

       o      https://fbb-git.gitlab.io/bobcat/: gitlab project page;

       o      bobcat_6.03.02-x.dsc: detached signature;

       o      bobcat_6.03.02-x.tar.gz: source archive;

       o      bobcat_6.03.02-x_i386.changes: change log;

       o      libbobcat1_6.03.02-x_*.deb: debian package containing the libraries;

       o      libbobcat1-dev_6.03.02-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).