FBB::ISharedStream - std::istream operations on shared memory

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

libbobcat-dev_6.07.01                               2005-2025                        FBB::ISharedStream(3bobcat)

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

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

       Debian Bobcat project files:

       o      libbobcat6: debian package containing the shared library, changelog and copyright note;

       o      libbobcat-dev: debian package containing the static library, headers, manual pages, and  developer
              info;

       Note  that by default exceptions thrown from within a std::stream object are caught by the stream object,
       setting its ios::failbit flag. To allow exceptions to leave a stream object, its exceptions member can be
       called, e.g., using:

           myStream.exceptions(ios::failbit | ios::badbit | ios::eofbit);

       o      ISharedStream():
              The default constructor defines a stub a ISharedStream object that cannot immediately be  used  to
              access shared memory. To use it, its member open must first be called.

       o      ISharedStream(size_tmaxSize,SizeUnitsizeUnit,std::ios::openmodeopenMode=std::ios::in,size_taccess=0600):
              This constructor creates an std::istream that interfaces to  a  shared  memory  segment  having  a
              capacity of at least maxSize*sizeUnit bytes. By default, the shared memory segment is opened for
              reading. Different from the open modes used for file streams, creating a shared memory stream with
              open  modes  ios::in is OK. In this case the shared memory segment is created and once information
              has been written to the shared memory by another process (or object) the information can be  read.
              The  shared  memory’s  access  rights  are  defined  by the access parameter, using the well-known
              (chmod(1)) way to define the access rights for the  owner,  the  group  and  others,  using  octal
              digits.  If  construction  succeeds  the shared memory is ready for use. If construction fails, an
              FBB::Exception is thrown.

       o      ISharedStream(intid,std::ios::openmodeopenMode=std::ios::in):
              This constructor creates an std::istream that 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.

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

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

       This class offers the features of the std::istream class, operating on shared memory.

       See the sharedstream(3bobcat) man page.

bobcat/isharedstream - defines the class interface

FBB::ISharedBuf (private inheritance),
       std::istream,
       FBB::SharedEnum__ (cf. sharedmemory(3bobcat) for a description of this last base class).

       All  members  of  std::istream,  and  the  enum  values kB,MB, and GB, defined by FBB::ISharedEnum__ are
       available.

       o      FBB::SharedConditionattachSharedCondition(std::ios::off_typeoffset,std::ios::seekdirorigin):
              Returns an FBB::SharedCondition(3) object, interfacing to a shared condition variable  located  at
              offset  offset  (relative  to origin) in the SharedMemory object to which the ISharedStream object
              interfaces.  This member does not alter the value returned by the stream’s tellg member.

              An FBB::Exception is thrown if the FBB::SharedCondition object could not be constructed.

       o      intid()const:
              The ID of the shared memory segment is returned.

       o      voidkill():
              Without locking the shared memory first,  all shared memory is returned to the  operating  system.
              The  FBB::ISharedStream  object  is  unusable after returning from kill. Other processes that were
              using the shared memory can continue to do so.

       o      voidmemInfo(std::ostream&out,charconst*end="\n"):
              Information about the ISharedMemory object is inserted 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. Following the information about the shaed memory, end is inserted into out.

       o      voidopen(size_tmaxSize,SizeUnitsizeUnit,std::ios::openmodeopenMode=std::ios::in,size_taccess=0600):
              This  member  creates  a  shared  memory  segment having a capacity of at least maxSize*sizeUnit
              bytes, and connects the shared memory segment to the FBB::ISharedStream. A matching  close  member
              does  not  exist and is not required. By default, the shared memory segment is opened for reading.
              Different from the open modes used for file streams, creating a shared  memory  stream  with  open
              modes  ios::in  is  OK. In this case the shared memory segment is created and once information has
              been written to the shared memory by another process it can be read. The  shared  memory’s  access
              rights  are  defined  by  the  access parameter, using the well-known (chmod(1)) way to define the
              access rights for the owner, the group and others, using octal digits.  If  opening  succeeds  the
              shared memory is ready for use. If opening fails, an FBB::Exception is thrown.

       o      voidopen(intid,std::ios::openmodeopenMode=std::ios::in):
              This  member  connects  the  FBB::ISharedStream  object to a shared memory segment having ID id. A
              matching close member does not exist and is not required. If opening succeeds the shared memory is
              ready for use. If opening fails  (e.g.,  no  shared  memory  segment  having  ID  id  exists),  an
              FBB::Exception is thrown.

       o      voidremove():
              The  shared  memory  is first locked. Next, all shared memory is returned to the operating system.
              The FBB::ISharedStream object is unusable after returning from remove. Other processes  that  were
              using the shared memory can continue to do so.

       o      booltruncate(std::streamsizeoffset):
              If  offset  is not exceeding the value returned by seekg(0,std::ios::end), then this latter value
              is changed to offset and true is returned. Otherwise false is returned, and the value returned  by
              seekg  is  not altered. If the value returned by tellg exceeded offset, tellg’s return value it is
              reduced to offset as well. Subsequent read operations on the shared memory  can  only  succeed  as
              long as tellg’s return value hasn’t reached the value offset.

       FBB::ISharedStream - std::istream operations on shared memory

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

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

       The enumSizeUnit 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

#include<bobcat/isharedstream>
       Linking option: -lpthread-lbobcat