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

Provided by: libbobcat-dev_6.03.02-2_amd64

NAME

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

SYNOPSIS

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

DESCRIPTION

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

NAMESPACE

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

INHERITS FROM

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

SIZEUNIT ENUMERATION

       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

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_t maxSize, SizeUnit sizeUnit, std::ios::openmode openMode =
std::ios::in, size_t access = 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(int id, std::ios::openmode openMode = 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.

MEMBER FUNCTIONS

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

       o      FBB::SharedCondition        attachSharedCondition(std::ios::off_type        offset,
              std::ios::seekdir origin):
              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      int id() const:
              The ID of the shared memory segment is returned.

       o      void kill():
              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      void memInfo(std::ostream &out, char const *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      void   open(size_t   maxSize,  SizeUnit  sizeUnit,  std::ios::openmode  openMode  =
              std::ios::in, size_t access = 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      void open(int id, std::ios::openmode openMode = 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      void remove():
              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      bool truncate(std::streamsize offset):
              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.

EXAMPLE

       See the sharedstream(3bobcat) man page.

FILES

       bobcat/isharedstream - defines the class interface

BUGS

       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);

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).