Ubuntu Manpage: FBB::SharedStreambuf - streambuf interfacing to shared memory

Provided by: libbobcat-dev_3.19.01-1ubuntu1_amd64

NAME

       FBB::SharedStreambuf - streambuf interfacing to shared memory

SYNOPSIS

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

DESCRIPTION

       This   class   implements   a  specialization  of  the  std::streambuf  class,  allowing  stream  classes
       (std::istream, std::ostream, FBB::ISharedStream, FBB::OSharedStream and FBB::SharedStream to perform  I/O
       operations on shared memory. FBB::SharedStreambuf objects interface to an FBB::SharedStream objects.

NAMESPACE

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

INHERITS FROM

       std::streambuf, FBB::SharedEnum__ (cf. sharedmemory(3bobcat) for a description of the latter class).

CONSTRUCTORS

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

o SharedStreambuf(size_t maxSize, SizeUnit sizeUnit, std::ios::openmode openMode = std::ios::in |
std::ios::out, size_t access = 0600):
This constructor creates a shared memory segment having a capacity of at least maxSize * sizeUnit
bytes. By default, the shared memory segment is opened for reading and writing. Different from the
open modes used for file streams, creating a shared memory stream with open modes ios::in |
ios::out is OK. In this case the shared memory segment is created and once information has been
written to the shared memory it can also be read again. 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 SharedStreambuf(int id, std::ios::openmode openMode = std::ios::in | std::ios::out):
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. Specifying the ios::trunc flag or specifying ios::out without
also specifying ios::in immediately clears the contents of the shared memory. ) Copy and move
constructors are not available.

OVERLOADED OPERATORS

              The overloaded move and copy assignment operators are not available.

MEMBER FUNCTIONS

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

       o      void clear():
              The shared memory is first locked. Next, all shared data segment are  returned  to  the  operating
              system,  after  which 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.

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

       o      void kill():
              Without  locking  the  shared  memory  the  FBB::SharedStreambuf’s  shared  memory is deleted. The
              FBB::SharedStreambuf object is unusable after returning from kill.

       o      void remove():
              The shared memory is  locked,  and  the  FBB::SharedStreambuf’s  shared  memory  is  deleted.  The
              FBB::SharedStreambuf object is unusable after returning from remove.

       o      void setMemory(SharedMemory &&tmp):
              The  anonymous  temporary  SharedMemory  object that is passed to setMemory defines the new shared
              memory segment to which the FBB::SharedStreambuf object interfaces. It can also be called to reuse
              a FBB::SharedStreambuf object again after calling kill or remove.

       o      void memInfo(std::ostream &out):
              Information  about the SharedMemory 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. The inserted information is not terminated by a final newline character.

PROTECTED MEMBER FUNCTION

       o      void setOpenMode(std::ios::openmode flag):
              The streambuf’s openmode is changed to the settings defined by flag. This member is used by, e.g.,
              SharedStream::open,  to  adapt the FBB::SharedStreambuf’s openmode to the flags that are passed to
              open.

EXAMPLE

       See the sharedstream(3bobcat) man page.

FILES

       bobcat/sharedstreambuf - 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);

DISTRIBUTION FILES

       o      bobcat_3.19.01-x.dsc: detached signature;

       o      bobcat_3.19.01-x.tar.gz: source archive;

       o      bobcat_3.19.01-x_i386.changes: change log;

       o      libbobcat1_3.19.01-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_3.19.01-x_*.deb: debian package holding the libraries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

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