[boost] Re: IOStreams formal review start

From: Pavel Vozenilek (pavel_vozenilek_at_[hidden])
Date: 2004-09-04 05:38:38

"Jonathan Turkanis" wrote:

> > Looking back on MoreIo library I recommend:
> >  - to prefere Iostreams for all overlapping functionality
> >  - to move the applicable rest from MoreIo into Iostreams
> >    with:
> >     - naming conventions taken from Iostreams
> >     - documentation look and feel from Iostreams
>
> I assume you view null_buf, pointerbuf, etc. as overlapping functionality.
What
> about 'streambuf wrapping'?
>
Doesn't feel to be big help but I could be easily wrong.
I have no strong opinion.

__________________________________________________________________
1. overview docs:

> Okay. What do you think of the pictures here: http://tinyurl.com/5v2ak?
Too much
> detail for the introduction?
>
Maybe some general, high level describing structure could come first.
If it can have up to three rectangles, people could keep it in short
term memory while reading futher.

Maybe use of colors can be reduced.

> >    Link to "adapters.html" is broken.
>
> Which link?
>
Oops. External link when not being online.

__________________________________________________________________
2. tutorial docs:
> >
>
> >    In example:
> >     in.open(634875);
> >    also stream example should be added,
> >    just to show how it is written.
>
> I don't understand.
>
streambuf_facade<random_source> in(5);
 in.close();
in.open(634875);

stream_facade<random_source>  in2(random_source(5));
in2.close();
in2.open(123);

> >    Sentence:
> >       "... and modifies it before returning it to the user."
> >    should be
> >       "... and modifies or eliminates it before returning it to the
user."
>
> Isn't elimination a type of modification?
>
I think this is one of disputed questions in philosophy.

Non-english readers may like if explicit.

> >  Shouldn't it have more expressive
> >    name e.g. input_filter_base? Maybe the source/sink too.
>
> I don't follow this.
>
The name 'input', without namespace qualification may:
 - suggest full featured, ready to use class, not something needed to be
extended
 - may clash when one uses "using namespace xyz" a lot

I personally like all base classes suffixed with "_base".

> >    filters.html link is broken.
>
> Which link?
>
Tutorial, section "Filtering Output", link with text "output_filter".

It points to file "filters.html", with superfluous 's' at the end of
filename.

> >    Generally, tutorial may be sprinkled with few more
> >    overcommented code snippets. They may be hide-able.
> >    Other docs won't suffer having them too.
>
> Okay. What do you mean by hideable? I'm hoping not to have to use any
javascript
> except for the menu.
>
Exactly that. Javascript powered "Show Example"/"Hide Example" code snippet.

 __________________________________________________________________
> > 4. docs: all <img> elements should have their width/height set in HTML
>
> For slow connections, I guess?
>
For people who switched off images by default.

__________________________________________________________________
> > 5. concepts docs: all concepts here can be also listen in table,
> >    sorted and with one line info.
> >
> >    The individual concepts should be added as sub tree into left panel.
> >    Dtto compression filters, etc.
> >    Every page should be accessible from left panel.
>
> I'll try to do this, but I might find that the menu is so big it takes too
long
> to load.
>
I got confused seeing pages in right panel for whom there was no left
panel item. It got me uneasy feeling I'll surely miss something.

__________________________________________________________________
> > 11. A collection of useful stream(buffer)s could be added into library,
> >     so they are handy to users:
>
> >  - repeater (some sequence of characters over and over)
> >    This one could ideally accept syntax used inn Boost.Assign.
> >    It would allow to easily create complex but predictable
> >    test data structures.
>
> Could you elaborate?
>
Thinko with Boost.Assigne. I meant something like:

repeater_stream(repeat(2, 'a', 'b', 'c', 'd', repeat('e', 4)), 'f', 'g');

which would produce sequence:

a, b, c, d, e, e, e, e,
a, b, c, d, e, e, e, e,
f, g
and again

The syntax is secondary, main point is that the generated data could
be typed easily.

> >  - 'a switcher'. Something what sends data into another stream
> >    but has method switch_to_other_stream(s). E.g. for circular logs.
>
> Doable, but presents some problems with buffer synchronization. There is
> currently no generic sync() function or Synchronizable concept.
>
Maybe this could be added (with Flush name)?

 __________________________________________________________________
> > 13. Possible feature of library
>
> > It would be nice to be able to 'send a command' down the stream
> > and have some part of chain picking it up and executing.
> > This way sender would not need to know anything about
> > current chain structure.
> >
> > Similarly one can imagine events going upstream.
> > If anyone handles them: OK, if not they will be ignored.
> >
> Sounds interesting. I believe this would have to rely on runtime rather
than
> compile-time polymorphism. I'll think about it.
>
Yes, maybe something typeless:

x_stream s;

unsigned invoked_count = s.send_command("cmd name", boost::any& parameter);

s.register_event_handler("event name", boost::function<void, stream_base*>
parameter);
s.unregister_event_handlers("event name");

x_stream
{
   bool on_command(const char* cmd, boost::any& parameter) {
      ....
      invoke_event("event_name");
      send_command("other command downstream", parameter);
      ....
      return true; // continue with this command downstream
   }
};

> > __________________________________________________________________
> > 14. May it be possible to add "synchronize panels" button into
> >     left panel? If clicked, it would expand and highlight item
> >     in left panel for currently opened page in right panel.
>
> The [link to this page] button already expands the tree to the current
page, if
> the tree contains a link to the current page. I guess highlighting would
be easy
> enough to do. I'm afraid some would find this annoying.
>
I noticed this button only now. When I am on page not listed in left panel
it just does left panel refresh. Maybe it could at least pick 'parent' or
'related'
page in left panel.

 __________________________________________________________________
> > 15, cloable.html: it should be explained (+ example) what
> >     'notification' here means.
>
> How's this:  A Closable filter or resource receives notifications -- via
the
> function <A HREF='...'>boost::io::close</A> --immediately before a
containing
> stream or stream buffer is closed.
>
I have uneasy feeling about the word 'notification'. Maybe "When you close
stream,
filters implementing Closeable concept will have their member function
close() called"
or so.

/Pavel