[boost] Re: IOStreams formal review start

From: Jonathan Turkanis (technews_at_[hidden])
Date: 2004-09-04 09:52:05

"Pavel Vozenilek" <pavel_vozenilek_at_[hidden]> wrote in message
news:chc5vj$rfd$1_at_sea.gmane.org...
>
> "Jonathan Turkanis" wrote:
> __________________________________________________________________
> 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);

Okay.

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

But input is not a base class. If anything, the convention would be to call it
input_tag. But since it's used a lot, I thought plain 'input' would be better.

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

Thanks.

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

I already went out of my way to make a case for the tree component, and I think
most people accepted it. The major selling point was that it's a module which
can be tested by itself on many browsers.

I'm not sure I want to be an advocate for more javascript, until the general
prohibition is lifted.

I do like the idea.

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

I see.

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

Okay.

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

Could you give an example application?

> > >  - '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)?

I had this before, but ripped it out when I added close -- probably prematurely.

>  _________________________________________________________________
> > > 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
>    }
> };

I'll have to give this more thought. Maybe I'll email you.

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

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

This is on my 'to do' list.

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

Okay.

Jonathan