plucky (3) sharedsegment.3bobcat.gz

Provided by: libbobcat-dev_6.06.02-1_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.06.02-x.dsc: detached signature;

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

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

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

       o      libbobcat1-dev_6.06.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’.

       This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).