.\"
.de Id
..
.de Sp
.if n .sp
.if t .sp 0.4
..
.TH diststream 2rheolef "rheolef-7.0" "rheolef-7.0" "rheolef-7.0"
.\" label: /*Class:odiststream
.SH NAME
\fBidiststream\fP, \fBodiststream\fP - distributed interface for large data streams
.\" skip: @clindex idiststream
.\" skip: @clindex odiststream
.\" skip: @findex din
.\" skip: @findex dout
.\" skip: @findex derr
.\" skip: @fiindex @file{.gz} gzip
.\" skip: @cindex RHEOPATH environment variable
.SH DESCRIPTION

This class provides a parallel and distributed stream interface for large
data management.
File decompresion is assumed using
\fBgzip\fP and a recursive search in a directory list
is provided for input.
.\" begin_example
.Sp
.nf
     odiststream foo("NAME", "suffix");
.Sp
.fi
.\" end_example
is similar
.\" begin_example
.Sp
.nf
     ofstream foo("NAME.suffix").
.Sp
.fi
.\" end_example
The main difference is that writing to \fBofstream\fP is executed on all processes
while \fBodiststream\fP manage nicely the multi-process environment.
For convenience, the standard streams \fBcin\fP, \fBcout\fP and \fBcerr\fP
are extended to \fBdin\fP, \fBdout\fP and \fBderr\fP.
Notice that, as \fBorheostream\fP (see rheostream(2)),
if \fINAME\fP does not end with `\fB.suffix'\fP, then
`\fB.suffix'\fP is automatically added.
By default, compression is performed on the fly with gzip, adding an additional `\fB.gz'\fP suffix.
The \fBflush\fP action is nicely handled in compression mode:
.\" begin_example
.Sp
.nf
     foo.flush();
.Sp
.fi
.\" end_example
This feature allows intermediate results to be available during long computations.
The compression can be deactivated while opening a file by an optional argument:
.\" begin_example
.Sp
.nf
     odiststream foo("NAME", "suffix", io::nogz);
.Sp
.fi
.\" end_example
An existing compressed file can be reopen in \fBappend\fP mode: new results will
be appended at the end of an existing file:
.\" begin_example
.Sp
.nf
     odiststream foo("NAME", "suffix", io::app);
.Sp
.fi
.\" end_example
.PP
Conversely,
.\" begin_example
.Sp
.nf
        irheostream foo("NAME","suffix");
.Sp
.fi
.\" end_example
is similar to
.\" begin_example
.Sp
.nf
        ifstream foo("NAME.suffix").
.Sp
.fi
.\" end_example
Also \fBidiststream\fP manage nicely the multi-process environment.
However, we look at a search path environment variable
\fBRHEOPATH\fP in order to find \fINAME\fP while suffix is assumed.
Moreover, \fBgzip\fP compressed files, ending
with the `\fB.gz'\fP suffix is assumed, and decompression is done.
.PP
.PP
.\" skip start:AUTHORS:

.\" skip start:DATE:
.\" skip start:METHODS:
.\" END
.SH IMPLEMENTATION
.\" begin_example
.Sp
.nf
class odiststream {
public:
  typedef std::size_t size_type;

// allocators/deallocators:

  odiststream();
  odiststream (std::string filename, std::string suffix = "",
              io::mode_type mode = io::out, const communicator& comm = communicator());
  odiststream (std::string filename,
              io::mode_type mode, const communicator& comm = communicator());
  odiststream (std::string filename, std::string suffix, const communicator& comm);
  odiststream (std::string filename, const communicator& comm);
  odiststream(std::ostream& os, const communicator& comm = communicator());
  ~odiststream();

// modifiers:

   void open (std::string filename, std::string suffix = "",
             io::mode_type mode = io::out, const communicator& comm = communicator());
   void open (std::string filename,
             io::mode_type mode, const communicator& comm = communicator());
   void open (std::string filename, std::string suffix,
             const communicator& comm);
   void open (std::string filename, const communicator& comm);
   void flush();
   void close();

// accessors:

   const communicator& comm() const { return _comm; }
   bool good() const;
   operator bool() const { return good(); }
   static size_type io_proc();

// internals:

   std::ostream& os();
   bool nop();

protected:
// data:
   std::ostream* _ptr_os;
   bool          _use_alloc;
   communicator  _comm;
};
.Sp
.fi
.\" end_example
.SH IMPLEMENTATION
.\" begin_example
.Sp
.nf
class idiststream {
public:
  typedef std::size_t size_type;

// allocators/deallocators:

  idiststream();
  idiststream (std::istream& is, const communicator& comm = communicator());
  idiststream (std::string filename, std::string suffix = "",
             const communicator& comm = communicator());
  ~idiststream();

// modifiers:

  void open (std::string filename, std::string suffix = "",
             const communicator& comm = communicator());
  void close();

// accessors:

  const communicator& comm() const { return _comm; }
  bool good() const;
  operator bool() const { return good(); }
  static size_type io_proc();

// internals:

  std::istream& is();
  bool nop();
  bool do_load();

protected:
// data:
  std::istream* _ptr_is;
  bool          _use_alloc;
  communicator  _comm;
};
.Sp
.fi
.\" end_example

.\" LENGTH = 1
.SH SEE ALSO
rheostream(2)
.SH COPYRIGHT
Copyright (C) 2000-2018 Pierre Saramito <Pierre.Saramito@imag.fr> GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.  There is NO WARRANTY, to the extent permitted by law.