[boost] IOStreams review

From: Dietmar Kuehl (dietmar_kuehl_at_[hidden])
Date: 2004-09-03 21:08:12

Hi,

let's start with the obvious formal requirement for review, i.e. the
answer to the question: Should this library be included into Boost? I
don't know. I have no strong feelings either way.

Maybe I'm too used to writing stream buffers without help from any
library but to me it is unclear whether this really makes things
simpler.  The number of different concepts is, at least to me, quite
confusing.  The library does, however, avoid a small fraction of
boilerplate code (mainly for buffer maintenance). Unfortunately it
does not at all address the really problematic area in stream buffers,
namely seeking: the interface of stream buffers is retained. This is
interface is, in my opinion, really hard to use. Typically, I don't
bother implementing it unless some specification requires me to do so.
On the other hand, I'm not using seeking with streams anyway.

The documentation should make clear that the filters are not usable as
temporary add-ons: I have some uses where I have an underlying stream
buffer which is used directly until a portion of the stream needs
special processing. At this point, a filter is used to process the
portio and normal processing is continued afterwards. For example,
when parsing a mail, a mime-decode filter is used to handle embedded
binary data. This assumes, however, that the filter synchronizes with
the underlying stream buffer.

On the ACCU 2003 conference JC (I can figure out the full name if
necessary...) presented the idea for creating filters which I really
liked. It looked something like this:

  filter_stream out(tee(std::cout) | encode | gzip | file("some file"));

This would create a stream which writes everything to 'std::cout'
and also encodes the stuff before sending it on to compress it and
finally write it to the file. I like this notation...

Finally, here are some issues I stumbled over in the documentation:

- The description for "boost::io::read()" seems wrong to me: "returning
  a value less than n indicates end-of-sequence". At least on POSIX
  systems, return less than the number of requested bytes indicates
  that *currently* no more characters are available. The next call may
  return more characters. This behavior could be useful e.g. when
  filtering: get a buffer from the underlying stream and pass on what
  is left from this buffer after filtering.

- On the "Filter" concept page, "OutputFilter" is not found (but it is
  reachable from the "InoutFilter" page).

- On the "SeekableFilter" concept page, I think the preconditions for
  "f.put()" and "f.write()" should be "output" rather than "input". At
  least, I would consider it confusing if "input" were right...
-- 
<mailto:dietmar_kuehl_at_[hidden]> <http://www.dietmar-kuehl.de/>
<http://www.contendix.com> - Software Development & Consulting