Re: [boost] Re: IOStreams formal review

From: John Torjo (john.lists_at_[hidden])
Date: 2004-09-07 00:41:09

> 
> 
>>tutorial.html:
>>
>>" The Iostreams Library allows users to create a standard input stream
>>or stream buffer by defining a classes with a single member function
>>read and several member types."
>>Q: What do you mean, by 'several member types'?
> 
> 
> Would you suggest a short description of these types in the tutorial, or just a
> comment that beginners don't need to worry about them, plus a link to a detailed
> explanation?

A link to a detailed info I think would suffice.
> 
> 
> 
>>"Buffering and the ability to put back characters come for free."
>>Q: Can I putback multiple chars, or just one?
> 
> 
> The size of the putback buffer can be specified when the stream or stream buffer
> is opened using open() or a constructor which specifies a resource -- That's if
> you're using stream_facade or streambuf_facade.

That's cool!
> 
> 
> 
> If you're writing a filter, say:
> 
> 
> 
>        struct my_filter : input_filter {
> 
>             template<typename Source>
> 
>             int get(Source& src)
> 
>            {
> 
>                  ... how many chars can I putback to src???
> 
>            }
> 
>        };
> 
> 
> 
> Here, it's only safe to put back one character. Currently source is a

For filters I guess I'm ok with a putback of 1.

> 
>>3.4 Output Filters
>>
>>Here your examples use 'filtered_streambuf', while in the Reference
>>section, you use 'filtering_streambuf'. Is this a typo?
> 
> 
> 
> 
> Yes. Thanks. The current name is 'filtering_streambuf'; in the past I've used
> 'filtered_streambuf' and 'filter_streambuf'. What's your preference?
> 
filtering_streambuf is better

> 
> 
>>policy_based_streams.html:
>>
>>I think you should visually show that streambuf_facade owns the policy
>>(the source). I had to look through the code to realize that. I have
>>later realized that you did say at the beginning " by delegating to a
>>contained instance of a policy class". Maybe emphasize the "contained
>>instance" (bold or something)?
> 
> 
> 
> 
> Larry Evans's comments convinced me that I need a prominent section on lifetime
> management issues. Here's what I suggested:
> 
> 
> 
> "Jonathan Turkanis" <technews_at_[hidden]> wrote:
> 
> 
>>Lifetime Management of Filters and Resources. This material should either go
>>under 'Concepts' in the User's Guide, or have its own section.
[...]

>>I believe these principles are fairly intuitive and easy to work with, but
> 
> they
> 
>>need to be spelled out in detail somewhere, and probably addressed in the
>>examples.
> 

Yup, this section would be great!
> 
> 
>>filtering_streambuf.html:
>>Again, by looking at the code, it seems that you own the streambufs. Is
>>that so? If it is, please state it in the docs (this is more of a
>>general issue - it applies to other classes as well).
>>I am worried about this, since I want to know what I need to destroy
>>manually, and what is destroyed automatically for me.
> 
> 
> 
> 
> All the internal streambufs are freed automatically by filtering_streambuf. If
> you write:
> 
> 
> 
>      filtering_ostream out;
>      out.push(base64_encoder()); // user-defined filter
>      out.push(my_stream);
> 
> You're responsible for freeing my_stream, if it was dynamically allocated.

Yes, that makes sense.
> 
> 
> 
> The library went through a large number of conventions for passing filters and
> resource (by pointer, by value,...). I forgot to discuss this in the latest
> rewrite of the rationale. The main point was exception safety.
> 
> 
> 
>>General issues:
>>I'm not sure if mixing streambuf and stream concepts is such a good idea.
>>As I've seen in your examples, you only use streams. Tnus, you don't use
>>streambufs directly.
>>
>>While having streambuf_facade is DEFINITELY a good idea, I think you
>>should have an  "Advanced" section, where you talk about the streambufs.
>>The rest of us are quite happy with having and using stream_facade.
> 
> 
> 
> 
> I think I need to add -- very early in the documentation -- a brief overview of
> the standard iostreams library, in which I
> 
> 
> 
> 1. indroduce the types streamsize and streamoff
> 
> 2. mention that basic_streambuf is the component which represent a connection to
> a data source/sink
> 
> 3. explain that streams represent the formatting layer of standard i/o, and that
> each stream contains a pointer to a streambuf to which its i/o functions and
> operators delegate.

Yup, you should definitely explain 3.
> 
> 
> 
> I can then explain that streambuf_facade is the principle component provided by
> the library, that stream_facade and filtering streams are really only
> convenience wrappers, but that the tutorial and examples will mostly use the
> wrappers since these are more familiar to existing users of the standard library
> and will probably be used most in practice.
> 
> How does that sound?

That sounds fine ;)

> 
> 
> 
>>-------------------------------------------
>>
>>     * What is your evaluation of the potential usefulness of the library?
>>
>>Very useful
>>
>>-------------------------------------------
>>
>>     * Did you try to use the library?  With what compiler?  Did you
>>have any problems?
>>
>>VC7.1 Compiled some examples - they worked ok, after I slightly modified
>>the jamfile.
>>(which makes me not like bjam even more - it makes it so hard to build
>>even trivial things)
> 
> 
> 
> 
> I'm no expert on Boost.Build -- I got the Jamfile to work on my system by trial
> and error.
> 

unfortunately most of us (including myself) do so.
That's just one of the reasons I don't like it (bjam).
> 
> 
> Could you explain why you added the lines
> 
>       <debug><runtime-link>static
>       <release><runtime-link>static
> 

It makes it possible to create a static runtime library, which you can 
later link an executable against (otherwise, it would be an executable 
dependent on a DLL or so).
I know this is a requirement for MSVC, not sure about other compilers 
though.

Best,
John

-- 
John Torjo
Freelancer
-- john_at_[hidden]
Contributing editor, C/C++ Users Journal
-- "Win32 GUI Generics" -- generics & GUI do mix, after all
-- http://www.torjo.com/win32gui/
-- v1.3beta released - check out splitter/simple_viewer,
    a File Explorer/Viewer all in about 200 lines of code!
Professional Logging Solution for FREE
-- http://www.torjo.com/code/logging.zip (logging           - C++)
-- http://www.torjo.com/logview/         (viewing/filtering - Win32)
-- http://www.torjo.com/logbreak/        (debugging         - Win32)