[boost] Re: IOStreams formal review start

From: Robert Ramey (ramey_at_[hidden])
Date: 2004-09-01 01:00:59

What is your evaluation of the documentation?

I've been reading through the documentation and I have a couple of questions
and observations.  I'm not sure I understand all the details so feel free to
correct me if I've miss understood something.

1) Generally the quality of the documentation is very good.

2) I have a problem with the name of the library - I find it very
misleading.  I would character the library by its main functionality

a) simplify the creation of new stream buffers.
b) permit stream buffers to be "chained" together to sequentially process
input and output.

So I think a better name would be "Stream Buffer Library"

Additionally it includes some very "thin" classes to make streams with with
the indicated buffers.  As I understand it this this basically replaces the
rdbuf member of the stream in the normal way.

In my view the tutorials don't make a clear distinction between stream
buffers and streams.  For example, I would prefer that the first one be:

Defining a Stream Buffer for a New Data Source.

Which would create a new stream buffer and then use in a stream created the
old fashion way.  Basically I think the tutorial is easier to understand if
one can add one concept at a time - especially when (in my view) they are
orthogonal concepts.

Same for the other tutorials.

The stream constructor can be in separate section.

This would also make it much easier to see where the overlap is with Daryl's
library.

Adaptors and Object Generators

Hmmm - I'm not sure "Adaptors" should be in here.  How about "Streambuffer
Generator" as it seems just to be shorthand for the above.

Filtering Input/Output

At first I was going to complain about this, but upon forming my complaint
it became clear how its supposed to be used. Again I was thrown by the
mixing of streambuffer and stream.  I would prefer to see this divided into
two pieces - making a chain of streambuffers and a final layer to used the
buffer in a standard stream.

It would characterize the source/sink concepts as "helpers" to building
streambufs but providing the end points of a chain of filters.  But that
leaves me with the question "What about a filter to a standard filebuf? What
do we use for  sink?  I'm sure its in there, I just didn't see it where I
expected to find it.  I presume its hidden in the filtered_?stream .. which
makes harder to see.  Of course this is the way its was designed so I guess
I'm complaining about this design decision.

3) Reference
=========
Another very professional job.  A few observations:

a) I'm sort of intrigued with the sequence that things are explained. For
example, it's hard to understand the concept of "chains" until the Filter
Stream is described.  These are relatively small points. 

b) I'm intrigued with the section "Code Converters".  How does this contrast
with using a codecvt facet?  What are we doing here that is not better than
adding a codecvt facet?  Might be better make a method of composition
("chaining") codecvt facets?  I don't know the answer.  As I went through
that part of the documentation this question occurred to me - it sort of
begs and answer.

4) Rationale

a) The section Generic Design left me stumped. The selection of conditional
verb tenses suggests that neither alternative was used. 

b) Interesting to me was that fact that the issue of streambuf vs stream is
dealt with explicitly.

5) What is your evaluation of the design?

a) I've already stated my reservations about the mixing of streams and
stream buffers.

b) the concept of "chaining" is quite different than what I would have
envisioned.  As I understand it, if 10 filters are chained together, this
system is going to require ten levels of function calls to get a character
in/out.  Someone is bound to object to this.  On the other hand,  this
system permits filter to be composed "chained" at runtime which may be
useful in some instances.
  
I would have expected something like the filters be composed at construction
time with templated constructors.  This would permit the inlined member
functions to be collapsed by the compiler to minimize copying.  The Dataflow
iterators in the serialization library manifest this expection.

I'm not saying that the method chosen by Jonathon isn't as good ( though I
might believe that) its just not what I expected.

c) I'm a little concerned as to where codecvt, wide character i/o etc fit
into this.  

d) I would be curious as to whether this is suitable for something other
than filebuf - e.g. stream adaptor for sockets i/o. ?

6) What is your evaluation of the implementation?

I didn't build the library or use in any tests so I recall can't contribute
to that assessment.

7) What is your evaluation of the potential usefulness of the library?

This is very useful and necessary.  Something like this is what I've hoped
for to complement the serialization library.  I envision something like this
combined with the serialization libray, combined with the mult-index set as
making one great in memory database.

Did you try to use the library?  With what compiler?  Did you have any
problems?

no

How much effort did you put into your evaluation? A glance? A quick reading?
In-depth study?

A couple hours with the documentation

Are you knowledgeable about the problem domain? 

Fairly knowledgable.

Do you think the library should be accepted as a Boost library?  Be sure to
say this explicitly so that your other comments don't obscure your overall
opinion.

I have reservations as stated above.  It very useful and necessary, and
seems (from the quality of the documentation) a high quality implementation.
If my choices were t accept or reject it as is I would accept it. Of course,
if others who've studied it in more depth confirm my reservations above, I
would like to see them addressed first.

Robert Ramey