ceph/src/boost/libs/iostreams/doc/concepts/device.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <HTML>
   3 <HEAD>
   4     <TITLE>Device</TITLE>
   5     <LINK REL="stylesheet" HREF="../../../../boost.css">
   6     <LINK REL="stylesheet" HREF="../theme/iostreams.css">
   7     <STYLE> P.concept { margin:.5em } </STYLE>
   8 </HEAD>
   9 <BODY>
  10
  11 <!-- Begin Banner -->
  12
  13     <H1 CLASS="title">Device</H1>
  14     <HR CLASS="banner">
  15
  16 <!-- End Banner -->
  17
  18 <H2>Description</H2>
  19
  20 <P>
  21     A Device provides access to one or two character sequences. It may provide access to an <SPAN CLASS="term">input sequence</SPAN>, for reading, an <SPAN CLASS="term">output sequence</SPAN>, for writing, or both. The relationship between the two sequences, as well as the operations that may be performed on them, depends on the Device type.
  22 </P>
  23 <P>
  24     Typically, Devices are class types which define one or more member functions <CODE>read</CODE>, <CODE>write</CODE> and <CODE>seek</CODE>. The concept Device is defined a bit more broadly, however, so that pre-existing types, such as standard streams and stream buffers, can be treated as models of Device, and so that Devices managing in-memory sequences can be optimized.
  25 </P>
  26 <P>
  27     Each Device type has an associated character type and category. The <A HREF="../guide/traits.html#char_type">character type</A> is the type of the characters in the sequence or sequences controlled by instances of the Device. The <A HREF="../guide/traits.html#category">category</A> is a tag structure which the Iostreams library relies on to determine which operations the Device supports. Its function is similar to the <CODE>iterator_category</CODE> member of <CODE>std::iterator_traits</CODE>.<A CLASS="footnote_ref" NAME="note_1_ref" HREF="#note_1"><SUP>[1]</SUP></A>
  28 </P>
  29 <P>
  30     There is one refinement of Device for each of the eight <A HREF="../guide/modes.html">modes</A>, and for each such refinement there is a corresponding refinement of <A HREF="filter.html">Filter</A>. In order to express this corresponce cleanly, it is helpful to include the requirements of the various refinements of Device in the definition of Device itself, qualified by category. The various refinements of Device can then be characterized exactly by the following definitions. For convenience, the requirements of the four most common Device refinements are also documented individually.
  31 </P>
  32
  33 <TABLE CELLPADDING="5" BORDER="1">
  34     <TR><TH>Concept</TH><TH>Definition</TH></TR>
  35     <TR>
  36         <TD><A href="source.html">Source</A></TD>
  37         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#input"><CODE>input</CODE></A></TD>
  38     </TR>
  39     <TR>
  40         <TD><A href="sink.html">Sink</A></TD>
  41         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#output"><CODE>output</CODE></A></TD>
  42     </TR>
  43     <TR>
  44         <TD><A href="bidirectional_device.html">BidirectionalDevice</A></TD>
  45         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#bidirectional"><CODE>bidirectional</CODE></A></TD>
  46     </TR>
  47     <TR>
  48         <TD><A href="seekable_device.html">SeekableDevice</A></TD>
  49         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#seekable"><CODE>seekable</CODE></A></TD>
  50     </TR>
  51     <TR>
  52         <TD>SeekableSource</TD>
  53         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#input_seekable"><CODE>input_seekable</CODE></A></TD>
  54     </TR>
  55     <TR>
  56         <TD>SeekableSink</TD>
  57         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#output_seekable"><CODE>output_seekable</CODE></A></TD>
  58     </TR>
  59     <TR>
  60         <TD>BidirectionalSeekableDevice</TD>
  61         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#bidirectional_seekable"><CODE>bidirectional_seekable</CODE></A></TD>
  62     </TR>
  63     <TR>
  64         <TD>DualSeekableDevice</TD>
  65         <TD>Refinement of Device with mode convertible to <A HREF="../guide/modes.html#dual_seekable"><CODE>dual_seekable</CODE></A></TD>
  66     </TR>
  67 </TABLE>
  68
  69 <H2>Note</H2>
  70
  71 <P>To be usable with the streams and stream buffers provided by the Boost Iostreams library, Devices must model <A HREF="blocking.html">Blocking</A>.
  72
  73 <H2>Standard Streams and Stream Buffers</H2>
  74
  75 <P>
  76     Standard streams and stream buffers are models of Device. It is not possible to tell the exact <A HREF="../guide/modes.html">mode</A> of an arbitrary stream or stream buffer, so the Iostreams library must make an educated guess. (<I>See</I> <A HREF="../classes/mode.html#type">Class Template <CODE>mode_of</CODE>.</A>) Since this guess may not accurately reflect the behavior of a particular stream or stream buffer, the user is allowed some flexibility when adding a stream or stream buffer to a <A HREF="../classes/chain.html">filter chain</A>. In such cases, it is up to the user to ensure that the behavior of the stream or stream buffer is consistent with the <A HREF="../guide/modes.html">mode</A> of the chain.
  77 </P>
  78
  79 <H2>Refinement of</H2>
  80
  81 <A NAME="types"></A>
  82 <H2>Associated Types</H2>
  83
  84 <TABLE CELLPADDING="5" BORDER="1">
  85     <TR><TD>Character type</TD><TD>The type of the characters in the controlled sequences</TD></TR>
  86     <TR>
  87         <TD>Category</TD>
  88         <TD>
  89             A type convertible to <A HREF="../guide/traits.html#category_tags"><CODE>device_tag</CODE></A> and to a unique <I>most-derived</I> <A HREF="../guide/modes.html#mode_tags">mode tag</A>
  90         </TD>
  91     </TR>
  92     <TR>
  93         <TD>Mode</TD>
  94         <TD>
  95             The unique <I>most-derived</I> <A HREF="../guide/modes.html#mode_tags">mode tag</A> to which Category is convertible
  96         </TD>
  97     </TR>
  98 </TABLE>
  99
 100 <H2>Notation</H2>
 101
 102 <TABLE CELLPADDING="2">
 103     <TR><TD><CODE>D</CODE></TD><TD>- A type which is a model of Device</TD></TR>
 104     <TR><TD><CODE>Ch</CODE></TD><TD>- The character type of <CODE>D</CODE></TD></TR>
 105     <TR><TD><CODE>dev</CODE></TD><TD>- Object of type <CODE>D</CODE></TD></TR>
 106     <TR><TD><CODE>s1</CODE></TD><TD>- Object of type <CODE>Ch*</CODE></TD></TR>
 107     <TR><TD><CODE>s2</CODE></TD><TD>- Object of type <CODE>const Ch*</CODE></TD></TR>
 108     <TR><TD><CODE>n</CODE></TD><TD>- Object of type <CODE>std::streamsize</CODE></TD></TR>
 109     <TR><TD><CODE>off</CODE></TD><TD>- Object of type <A HREF="../functions/positioning.html#synopsis"><CODE>stream_offset</CODE></A></TD></TR>
 110     <TR><TD><CODE>way</CODE></TD><TD>- Object of type <CODE>std::ios_base::seekdir</CODE></TD></TR>
 111     <TR><TD><CODE>which</CODE></TD><TD>- Object of type <CODE>std::ios_base::openmode</CODE></TD></TR>
 112     <TR><TD><CODE>io</CODE></TD><TD>- Alias for namespace <CODE>boost::iostreams</CODE></TD></TR>
 113 </TABLE>
 114
 115
 116 <A NAME="expressions"></A>
 117 <H2>Valid Expressions &#8212; Typenames</H2>
 118
 119 <TABLE CELLPADDING="5" BORDER="1">
 120     <TR><TH>Expression</TH><TH>Expression Type</TH></TR>
 121     <TR>
 122         <TD><CODE>typename <A HREF="../guide/traits.html#char_type_of_ref">char_type_of</A>&lt;D&gt;::type</CODE></TD>
 123         <TD><CODE>typename</CODE> of the character type</TD>
 124     </TR>
 125     <TR>
 126         <TD><CODE>typename <A HREF="../guide/traits.html#category_ref">category_of</A>&lt;D&gt;::type</CODE></TD>
 127         <TD><CODE>typename</CODE> of the category</TD>
 128     </TR>
 129 </TABLE>
 130
 131 <H2>Valid Expressions / Semantics &#8212; Input</H2>
 132
 133 <TABLE CELLPADDING="5" BORDER="1">
 134     <TR><TH>Expression</TH><TH>Expression Type</TH><TH>Category Precondition</TH><TH>Semantics</TH></TR>
 135     <TR>
 136         <TD><PRE CLASS="plain_code"><CODE><A HREF="../functions/read.html">io::read</A>(dev, s1, n)</CODE></PRE></TD>
 137         <TD><CODE>std::streamsize</CODE></TD>
 138         <TD>
 139             Convertible to <A HREF="../guide/modes.html#mode_tags"><CODE>input</CODE></A> but not to <A HREF="../guide/traits.html#category_tags"><CODE>direct_tag</CODE></A>
 140         </TD>
 141         <TD>
 142             Reads up to <CODE>n</CODE> characters from the sequence controlled by <CODE>dev</CODE> into <CODE>s1</CODE>, returning the number of characters read, or <CODE>-1</CODE> to indicate end-of-sequence
 143         </TD>
 144     </TR>
 145     <TR>
 146         <TD><PRE CLASS="plain_code"><CODE>dev.input_sequence()</CODE></PRE></TD>
 147         <TD><PRE CLASS="plain_code"><CODE>std::pair&lt;Ch*,Ch*&gt;</CODE></PRE></TD>
 148         <TD>
 149             Convertible to <A HREF="../guide/modes.html#mode_tags"><CODE>input</CODE></A> and to <A HREF="../guide/traits.html#category_tags"><CODE>direct_tag</CODE></A>
 150         </TD>
 151         <TD>Returns a pair of pointers delimiting the sequence controlled by <CODE>dev</CODE></TD>
 152     </TR>
 153 </TABLE>
 154
 155 <H2>Valid Expressions / Semantics &#8212; Output</H2>
 156
 157 <TABLE CELLPADDING="5" BORDER="1">
 158     <TR><TH>Expression</TH><TH>Expression Type</TH><TH>Category Precondition</TH><TH>Semantics</TH></TR>
 159     <TR>
 160         <TD><PRE CLASS="plain_code"><CODE><A HREF="../functions/write.html">io::write</A>(dev, s2, n)</CODE></PRE></TD>
 161         <TD><CODE>std::streamsize</CODE></TD>
 162         <TD>
 163             Convertible to <A HREF="../guide/modes.html#mode_tags"><CODE>output</CODE></A> but not to <A HREF="../guide/traits.html#category_tags"><CODE>direct_tag</CODE></A>
 164         </TD>
 165         <TD>
 166             Writes up to <CODE>n</CODE> characters from the sequence beginning at <CODE>s2</CODE> to the sequence controlled by <CODE>dev</CODE>, returning the number of characters written
 167         </TD>
 168     </TR>
 169     <TR>
 170         <TD><PRE CLASS="plain_code"><CODE>dev.output_sequence()</CODE></PRE></TD>
 171         <TD><PRE CLASS="plain_code"><CODE>std::pair&lt;Ch*,Ch*&gt;</CODE></PRE></TD>
 172         <TD>
 173             Convertible to <A HREF="../guide/modes.html#mode_tags"><CODE>output</CODE></A> and to <A HREF="../guide/traits.html#category_tags"><CODE>direct_tag</CODE></A>
 174         </TD>
 175         <TD>Returns a pair of pointers delimiting the sequence controlled by <CODE>dev</CODE></TD>
 176     </TR>
 177 </TABLE>
 178
 179 <H2>Valid Expressions / Semantics &#8212; Random-Access</H2>
 180
 181 <TABLE CELLPADDING="5" BORDER="1">
 182     <TR><TH>Expression</TH><TH>Expression Type</TH><TH>Category Precondition</TH><TH>Semantics</TH></TR>
 183     <TR>
 184         <TD><PRE CLASS="plain_code"><CODE><A HREF="../functions/seek.html">io::seek</A>(dev, off, way)</CODE></PRE></TD>
 185         <TD><CODE>std::streampos</CODE></TD>
 186         <TD>
 187             Convertible to <A HREF="../guide/modes.html#mode_tags"><CODE>seekable</CODE></A> but not to <A HREF="../guide/traits.html#category_tags"><CODE>direct_tag</CODE></A>
 188         </TD>
 189         <TD>
 190             <P CLASS="concept">
 191                 Advances the read/write head by <CODE>off</CODE> characters, returning the new position, where the offset is calculated from:
 192             </P>
 193             <UL STYLE="margin:0,0,0,auto">
 194                 <LI STYLE="list-style-type:disc;list-style-image:none">the start of the sequence if <CODE>way</CODE> is <CODE>ios_base::beg</CODE>
 195                 <LI STYLE="list-style-type:disc;list-style-image:none">the current position if <CODE>way</CODE> is <CODE>ios_base::cur</CODE>
 196                 <LI STYLE="list-style-type:disc;list-style-image:none">the end of the sequence if <CODE>way</CODE> is <CODE>ios_base::end</CODE>
 197             </UL>
 198         </TD>
 199     </TR>
 200     <TR>
 201         <TD><PRE CLASS="plain_code"><CODE><A HREF="../functions/seek.html">io::seek</A>(dev, off, way, which)</CODE></PRE></TD>
 202         <TD><CODE>std::streampos</CODE></TD>
 203         <TD>
 204             Convertible to <A HREF="../guide/modes.html#mode_tags"><CODE>dual_seekable</CODE></A> or <A HREF="../guide/modes.html#mode_tags"><CODE>bidirectional_seekable</CODE></A> but not to <A HREF="../guide/traits.html#category_tags"><CODE>direct_tag</CODE></A>
 205         </TD>
 206         <TD>
 207              <P CLASS="concept">
 208                 Advances the read head (if <CODE>which</CODE> is <CODE>std::ios_base::in</CODE>), the write head (if <CODE>which</CODE> is <CODE>std::ios_base::out</CODE>) or both heads (if <CODE>which</CODE> is <CODE>std::ios_base::in | std::ios_base::out</CODE>) by <CODE>off</CODE> characters, returning the new position, where the offset is calculated from
 209             </P>
 210             <UL STYLE="margin:0,0,0,auto">
 211                 <LI STYLE="list-style-type:disc;list-style-image:none">the start of the sequence if <CODE>way</CODE> is <CODE>ios_base::beg</CODE>
 212                 <LI STYLE="list-style-type:disc;list-style-image:none">the current position if <CODE>way</CODE> is <CODE>ios_base::cur</CODE>
 213                 <LI STYLE="list-style-type:disc;list-style-image:none">the end of the sequence if <CODE>way</CODE> is <CODE>ios_base::end</CODE>
 214             </UL>
 215             <P CLASS="concept">
 216                 The result is undefined if <CODE>way</CODE> is <CODE>ios_base::cur</CODE> and <CODE>which</CODE> is <CODE>(std::ios_base::in | std::ios_base::out)</CODE>.
 217             </P>
 218         </TD>
 219     </TR>
 220 </TABLE>
 221
 222 <H2>Exceptions</H2>
 223
 224 <P>
 225     Errors which occur during the execution of <CODE>read</CODE>, <CODE>write</CODE>, <CODE>seek</CODE>, <CODE>input_sequence</CODE> or <CODE>output_sequence</CODE> are indicated by throwing exceptions. Reaching the end of the input sequence is not an error, but attempting to write past the end of the output sequence is.
 226 </P>
 227
 228 <P>
 229     After an exception is thrown, a Device must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour.
 230 </P>
 231
 232 <H2>Models</H2>
 233
 234 <P>
 235     See <A HREF="source.html">Source</A>, <A HREF="sink.html">Sink</A>, <A HREF="bidirectional_device.html">BidirectionalDevice</A> and <A HREF="seekable_device.html">SeekableDevice</A>.
 236 </P>
 237
 238 <!-- Begin Footnotes -->
 239
 240 <HR>
 241
 242 <P>
 243     <A CLASS="footnote_ref" NAME="note_1" HREF="#note_1_ref"><SUP>[1]</SUP></A><A CLASS="bib_ref" HREF="../bibliography.html#iso">[I<SPAN STYLE="font-size:80%">SO</SPAN>]</A>, 24.3.1. <I>See</I> <A HREF="http://www.boost.org/more/generic_programming.html#tag_dispatching" TARGET="_top">Tag Dispatching</A> for a discussion.
 244 </P>
 245
 246 <!-- End Footnotes -->
 247
 248 <!-- Begin Footer -->
 249
 250 <HR>
 251
 252 <P CLASS="copyright">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; Copyright 2004-2007 <a href="http://www.coderage.com/turkanis/" target="_top">Jonathan Turkanis</a></P>
 253 <P CLASS="copyright">
 254     Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>)
 255 </P>
 256
 257 <!-- End Footer -->
 258
 259 </BODY>