Re: [boost] [iostreams] understanding the models

From: Jonathan Turkanis (turkanis_at_[hidden])
Date: 2008-01-05 16:13:54

Benjamin Collins wrote:
 > I'm trying to write a device for iostreams, but I'm having a hard time
 > understanding how the current sources and the models explained in the
 > documentation are in agreement.  Maybe I'm shooting myself in the foot
 > by never being able to work on this for more than 30 minutes at a time
 > and having that 30 minutes be late at night, but...

Sorry for the confusion; I tried to keep the concepts as simple as
intuitive as possible while still allowing the import optimization for
cases (like mapped files) where the data is presented directly in memory
instead of incrementally using read() or write().

You happen to be looking at models of Direct
(http://www.boost.org/libs/iostreams/doc/index.html?path=4.1.1.4). The
technical requirements for modeling Direct are spelled out in the
documentation for Device
(http://www.boost.org/libs/iostreams/doc/index.html?path=4.1.1.3); the
relevant table rows are those in which the "Category Precondition"
include "convertible to direct_tag."

 > Anyway, it seems odd to me - for example, the
 > boost::iostreams::mapped_file_source class has the following category
 > of source_tag + direct_tag + closable_tag, and has member functions
 > open(), size(), data(), begin(), and end().

 > None of these are particularly surprising.  After all - a mapped_file
 > has to be open()ed at some point.  But under what model as defined in
 > the docs?

I provided the open() function (or maybe inherited it from Craig
Henderson) so that the mapped_file devices could be used by themselves,
without streams or filter chains. If you're using a mapped_file
indirectly via one of the stream/stream buffer/chain templates provided
by the library, open() is never called; instead, when you want a
stream/stream buffer/chain to perform I/O using a mapped_file, you do
one of the following:

- explicitly construct a mapped_file f and then call
   stream/stream_buffer::open(f) or
   filtering_stream/filtering_streambuf/chain::push(f), OR
- pass mapped_file constructor params to stream/stream_buffer::open(f)
   or filtering_stream/filtering_streambuf/chain::push(f) and let the
   iostreams library construct a mapped_file for you.

 > In other words, how and when is that function called, and how does a
 > stream_buffer know he can call open() on a particular device?  Also,
 > the documentation indicates that a source device needs to support the
 > read() function - but mapped_file_source has no read() (maybe because
 > it is convertible to 'direct'?).
 >

Yes, you need to look at the specs for Direct.

-- 
Jonathan Turkanis
CodeRage
http://www.coderage.com