oracular (3) sharedmemory.3bobcat.gz

Provided by: libbobcat-dev_6.06.01-1_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::SharedBuf,
       defining  the  `device’  to  which  FBB::SharedBuf  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 (and assignment operators) 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.

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), sharedbuf(3bobcat)

BUGS

       None Reported.

BOBCAT PROJECT FILES

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

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

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

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

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

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