|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r49497 - in trunk: boost/asio libs/asio/doc
From: chris_at_[hidden]
Date: 2008-10-30 21:09:46
Author: chris_kohlhoff
Date: 2008-10-30 21:09:45 EDT (Thu, 30 Oct 2008)
New Revision: 49497
URL: http://svn.boost.org/trac/boost/changeset/49497
Log:
Add more documentation for asio::streambuf.
Text files modified:
trunk/boost/asio/basic_streambuf.hpp | 163 ++++++++++++++++++++++-
trunk/libs/asio/doc/reference.qbk | 269 ++++++++++++++++++++++++++++++++++-----
2 files changed, 386 insertions(+), 46 deletions(-)
Modified: trunk/boost/asio/basic_streambuf.hpp
==============================================================================
--- trunk/boost/asio/basic_streambuf.hpp (original)
+++ trunk/boost/asio/basic_streambuf.hpp 2008-10-30 21:09:45 EDT (Thu, 30 Oct 2008)
@@ -34,6 +34,73 @@
namespace asio {
/// Automatically resizable buffer class based on std::streambuf.
+/**
+ * The @c basic_streambuf class is derived from @c std::streambuf to associate
+ * the streambuf's input and output sequences with one or more character
+ * arrays. These character arrays are internal to the @c basic_streambuf
+ * object, but direct access to the array elements is provided to permit them
+ * to be used efficiently with I/O operations. Characters written to the output
+ * sequence of a @c basic_streambuf object are appended to the input sequence
+ * of the same object.
+ *
+ * The @c basic_streambuf class's public interface is intended to permit the
+ * following implementation strategies:
+ *
+ * @li A single contiguous character array, which is reallocated as necessary
+ * to accommodate changes in the size of the character sequence. This is the
+ * implementation approach currently used in Asio.
+ *
+ * @li A sequence of one or more character arrays, where each array is of the
+ * same size. Additional character array objects are appended to the sequence
+ * to accommodate changes in the size of the character sequence.
+ *
+ * @li A sequence of one or more character arrays of varying sizes. Additional
+ * character array objects are appended to the sequence to accommodate changes
+ * in the size of the character sequence.
+ *
+ * The constructor for basic_streambuf accepts a @c size_t argument specifying
+ * the maximum of the sum of the sizes of the input sequence and output
+ * sequence. During the lifetime of the @c basic_streambuf object, the following
+ * invariant holds:
+ * @code size() <= max_size()@endcode
+ * Any member function that would, if successful, cause the invariant to be
+ * violated shall throw an exception of class @c std::length_error.
+ *
+ * The constructor for @c basic_streambuf takes an Allocator argument. A copy
+ * of this argument is used for any memory allocation performed, by the
+ * constructor and by all member functions, during the lifetime of each @c
+ * basic_streambuf object.
+ *
+ * @par Examples
+ * Writing directly from an streambuf to a socket:
+ * @code
+ * boost::asio::streambuf b;
+ * std::ostream os(&b);
+ * os << "Hello, World!\n";
+ *
+ * // try sending some data in input sequence
+ * size_t n = sock.send(b.data());
+ *
+ * b.consume(n); // sent data is removed from input sequence
+ * @endcode
+ *
+ * Reading from a socket directly into a streambuf:
+ * @code
+ * boost::asio::streambuf b;
+ *
+ * // reserve 512 bytes in output sequence
+ * boost::asio::streambuf::const_buffers_type bufs = b.prepare(512);
+ *
+ * size_t n = sock.receive(bufs);
+ *
+ * // received data is "committed" from output sequence to input sequence
+ * b.commit(n);
+ *
+ * std::istream is(&b);
+ * std::string s;
+ * is >> s;
+ * @endcode
+ */
template <typename Allocator = std::allocator<char> >
class basic_streambuf
: public std::streambuf,
@@ -41,17 +108,21 @@
{
public:
#if defined(GENERATING_DOCUMENTATION)
- /// The type used to represent the get area as a list of buffers.
+ /// The type used to represent the input sequence as a list of buffers.
typedef implementation_defined const_buffers_type;
- /// The type used to represent the put area as a list of buffers.
+ /// The type used to represent the output sequence as a list of buffers.
typedef implementation_defined mutable_buffers_type;
#else
typedef boost::asio::const_buffers_1 const_buffers_type;
typedef boost::asio::mutable_buffers_1 mutable_buffers_type;
#endif
- /// Construct a buffer with a specified maximum size.
+ /// Construct a basic_streambuf object.
+ /**
+ * Constructs a streambuf with the specified maximum size. The initial size
+ * of the streambuf's input sequence is 0.
+ */
explicit basic_streambuf(
std::size_t max_size = (std::numeric_limits<std::size_t>::max)(),
const Allocator& allocator = Allocator())
@@ -64,34 +135,86 @@
setp(&buffer_[0], &buffer_[0] + pend);
}
- /// Return the size of the get area in characters.
+ /// Get the size of the input sequence.
+ /**
+ * @returns The size of the input sequence. The value is equal to that
+ * calculated for @c s in the following code:
+ * @code
+ * size_t s = 0;
+ * const_buffers_type bufs = data();
+ * const_buffers_type::const_iterator i = bufs.begin();
+ * while (i != bufs.end())
+ * {
+ * const_buffer buf(*i++);
+ * s += buffer_size(buf);
+ * }
+ * @endcode
+ */
std::size_t size() const
{
return pptr() - gptr();
}
- /// Return the maximum size of the buffer.
+ /// Get the maximum size of the basic_streambuf.
+ /**
+ * @returns The allowed maximum of the sum of the sizes of the input sequence
+ * and output sequence.
+ */
std::size_t max_size() const
{
return max_size_;
}
- /// Get a list of buffers that represents the get area.
+ /// Get a list of buffers that represents the input sequence.
+ /**
+ * @returns An object of type @c const_buffers_type that satisfies
+ * ConstBufferSequence requirements, representing all character arrays in the
+ * input sequence.
+ *
+ * @note The returned object is invalidated by any @c basic_streambuf member
+ * function that modifies the input sequence or output sequence.
+ */
const_buffers_type data() const
{
return boost::asio::buffer(boost::asio::const_buffer(gptr(),
(pptr() - gptr()) * sizeof(char_type)));
}
- /// Get a list of buffers that represents the put area, with the given size.
- mutable_buffers_type prepare(std::size_t size)
+ /// Get a list of buffers that represents the output sequence, with the given
+ /// size.
+ /**
+ * Ensures that the output sequence can accommodate @c n characters,
+ * reallocating character array objects as necessary.
+ *
+ * @returns An object of type @c mutable_buffers_type that satisfies
+ * MutableBufferSequence requirements, representing character array objects
+ * at the start of the output sequence such that the sum of the buffer sizes
+ * is @c n.
+ *
+ * @throws std::length_error If <tt>size() + n > max_size()</tt>.
+ *
+ * @note The returned object is invalidated by any @c basic_streambuf member
+ * function that modifies the input sequence or output sequence.
+ */
+ mutable_buffers_type prepare(std::size_t n)
{
- reserve(size);
+ reserve(n);
return boost::asio::buffer(boost::asio::mutable_buffer(
- pptr(), size * sizeof(char_type)));
+ pptr(), n * sizeof(char_type)));
}
- /// Move the start of the put area by the specified number of characters.
+ /// Move characters from the output sequence to the input sequence.
+ /**
+ * Appends @c n characters from the start of the output sequence to the input
+ * sequence. The beginning of the output sequence is advanced by @c n
+ * characters.
+ *
+ * Requires a preceding call <tt>prepare(x)</tt> where <tt>x >= n</tt>, and
+ * no intervening operations that modify the input or output sequence.
+ *
+ * @throws std::length_error If @c n is greater than the size of the output
+ * sequence.
+ */
void commit(std::size_t n)
{
if (pptr() + n > epptr())
@@ -100,7 +223,12 @@
setg(eback(), gptr(), pptr());
}
- /// Move the start of the get area by the specified number of characters.
+ /// Remove characters from the input sequence.
+ /**
+ * Removes @c n characters from the beginning of the input sequence.
+ *
+ * @throws std::length_error If <tt>n > size()</tt>.
+ */
void consume(std::size_t n)
{
if (gptr() + n > pptr())
@@ -111,6 +239,10 @@
protected:
enum { buffer_delta = 128 };
+ /// Override std::streambuf behaviour.
+ /**
+ * Behaves according to the specification of @c std::streambuf::underflow().
+ */
int_type underflow()
{
if (gptr() < pptr())
@@ -124,6 +256,13 @@
}
}
+ /// Override std::streambuf behaviour.
+ /**
+ * Behaves according to the specification of @c std::streambuf::overflow(),
+ * with the specialisation that @c std::length_error is thrown if appending
+ * the character to the input sequence would require the condition
+ * <tt>size() > max_size()</tt> to be true.
+ */
int_type overflow(int_type c)
{
if (!traits_type::eq_int_type(c, traits_type::eof()))
Modified: trunk/libs/asio/doc/reference.qbk
==============================================================================
--- trunk/libs/asio/doc/reference.qbk (original)
+++ trunk/libs/asio/doc/reference.qbk 2008-10-30 21:09:45 EDT (Thu, 30 Oct 2008)
@@ -26321,14 +26321,14 @@
[
[[link boost_asio.reference.basic_streambuf.const_buffers_type [*const_buffers_type]]]
- [The type used to represent the get area as a list of buffers. ]
+ [The type used to represent the input sequence as a list of buffers. ]
]
[
[[link boost_asio.reference.basic_streambuf.mutable_buffers_type [*mutable_buffers_type]]]
- [The type used to represent the put area as a list of buffers. ]
+ [The type used to represent the output sequence as a list of buffers. ]
]
@@ -26340,37 +26340,37 @@
[
[[link boost_asio.reference.basic_streambuf.basic_streambuf [*basic_streambuf]]]
- [Construct a buffer with a specified maximum size. ]
+ [Construct a basic_streambuf object. ]
]
[
[[link boost_asio.reference.basic_streambuf.commit [*commit]]]
- [Move the start of the put area by the specified number of characters. ]
+ [Move characters from the output sequence to the input sequence. ]
]
[
[[link boost_asio.reference.basic_streambuf.consume [*consume]]]
- [Move the start of the get area by the specified number of characters. ]
+ [Remove characters from the input sequence. ]
]
[
[[link boost_asio.reference.basic_streambuf.data [*data]]]
- [Get a list of buffers that represents the get area. ]
+ [Get a list of buffers that represents the input sequence. ]
]
[
[[link boost_asio.reference.basic_streambuf.max_size [*max_size]]]
- [Return the maximum size of the buffer. ]
+ [Get the maximum size of the basic_streambuf. ]
]
[
[[link boost_asio.reference.basic_streambuf.prepare [*prepare]]]
- [Get a list of buffers that represents the put area, with the given size. ]
+ [Get a list of buffers that represents the output sequence, with the given size. ]
]
[
[[link boost_asio.reference.basic_streambuf.size [*size]]]
- [Return the size of the get area in characters. ]
+ [Get the size of the input sequence. ]
]
]
@@ -26381,7 +26381,7 @@
[
[[link boost_asio.reference.basic_streambuf.overflow [*overflow]]]
- []
+ [Override std::streambuf behaviour. ]
]
[
@@ -26391,21 +26391,79 @@
[
[[link boost_asio.reference.basic_streambuf.underflow [*underflow]]]
- []
+ [Override std::streambuf behaviour. ]
]
]
+The `basic_streambuf` class is derived from `std::streambuf` to associate the streambuf's input and output sequences with one or more character arrays. These character arrays are internal to the `basic_streambuf` object, but direct access to the array elements is provided to permit them to be used efficiently with I/O operations. Characters written to the output sequence of a `basic_streambuf` object are appended to the input sequence of the same object.
+
+The `basic_streambuf` class's public interface is intended to permit the following implementation strategies:
+
+
+* A single contiguous character array, which is reallocated as necessary to accommodate changes in the size of the character sequence. This is the implementation approach currently used in Asio.
+
+* A sequence of one or more character arrays, where each array is of the same size. Additional character array objects are appended to the sequence to accommodate changes in the size of the character sequence.
+
+* A sequence of one or more character arrays of varying sizes. Additional character array objects are appended to the sequence to accommodate changes in the size of the character sequence.
+
+The constructor for basic_streambuf accepts a `size_t` argument specifying the maximum of the sum of the sizes of the input sequence and output sequence. During the lifetime of the `basic_streambuf` object, the following invariant holds:
+
+ size() <= max_size()
+
+
+Any member function that would, if successful, cause the invariant to be violated shall throw an exception of class `std::length_error`.
+
+The constructor for `basic_streambuf` takes an Allocator argument. A copy of this argument is used for any memory allocation performed, by the constructor and by all member functions, during the lifetime of each `basic_streambuf` object.
+
+
+[heading Examples]
+
+Writing directly from an streambuf to a socket:
+
+ boost::asio::streambuf b;
+ std::ostream os(&b);
+ os << "Hello, World!\n";
+
+ // try sending some data in input sequence
+ size_t n = sock.send(b.data());
+
+ b.consume(n); // sent data is removed from input sequence
+
+
+
+
+Reading from a socket directly into a streambuf:
+
+ boost::asio::streambuf b;
+
+ // reserve 512 bytes in output sequence
+ boost::asio::streambuf::const_buffers_type bufs = b.prepare(512);
+
+ size_t n = sock.receive(bufs);
+
+ // received data is "committed" from output sequence to input sequence
+ b.commit(n);
+
+ std::istream is(&b);
+ std::string s;
+ is >> s;
+
+
+
+
[section:basic_streambuf basic_streambuf::basic_streambuf]
-[indexterm2 basic_streambuf..basic_streambuf] Construct a buffer with a specified maximum size.
+[indexterm2 basic_streambuf..basic_streambuf] Construct a basic_streambuf object.
basic_streambuf(
std::size_t max_size = (std::numeric_limits< std::size_t >::max)(),
const Allocator & allocator = Allocator());
+Constructs a streambuf with the specified maximum size. The initial size of the streambuf's input sequence is 0.
+
[endsect]
@@ -26413,12 +26471,27 @@
[section:commit basic_streambuf::commit]
-[indexterm2 commit..basic_streambuf] Move the start of the put area by the specified number of characters.
+[indexterm2 commit..basic_streambuf] Move characters from the output sequence to the input sequence.
void commit(
std::size_t n);
+Appends `n` characters from the start of the output sequence to the input sequence. The beginning of the output sequence is advanced by `n` characters.
+
+Requires a preceding call `prepare(x)` where `x >= n`, and no intervening operations that modify the input or output sequence.
+
+
+[heading Exceptions]
+
+
+[variablelist
+
+[[std::length_error][If `n` is greater than the size of the output sequence. ]]
+
+]
+
+
[endsect]
@@ -26426,7 +26499,7 @@
[section:const_buffers_type basic_streambuf::const_buffers_type]
-[indexterm2 const_buffers_type..basic_streambuf] The type used to represent the get area as a list of buffers.
+[indexterm2 const_buffers_type..basic_streambuf] The type used to represent the input sequence as a list of buffers.
typedef implementation_defined const_buffers_type;
@@ -26439,12 +26512,25 @@
[section:consume basic_streambuf::consume]
-[indexterm2 consume..basic_streambuf] Move the start of the get area by the specified number of characters.
+[indexterm2 consume..basic_streambuf] Remove characters from the input sequence.
void consume(
std::size_t n);
+Removes `n` characters from the beginning of the input sequence.
+
+
+[heading Exceptions]
+
+
+[variablelist
+
+[[std::length_error][If `n > size()`. ]]
+
+]
+
+
[endsect]
@@ -26452,31 +26538,47 @@
[section:data basic_streambuf::data]
-[indexterm2 data..basic_streambuf] Get a list of buffers that represents the get area.
+[indexterm2 data..basic_streambuf] Get a list of buffers that represents the input sequence.
const_buffers_type data() const;
+[heading Return Value]
+
+An object of type `const_buffers_type` that satisfies ConstBufferSequence requirements, representing all character arrays in the input sequence.
+
+[heading Remarks]
+
+The returned object is invalidated by any `basic_streambuf` member function that modifies the input sequence or output sequence.
+
+
+
[endsect]
[section:max_size basic_streambuf::max_size]
-[indexterm2 max_size..basic_streambuf] Return the maximum size of the buffer.
+[indexterm2 max_size..basic_streambuf] Get the maximum size of the basic_streambuf.
std::size_t max_size() const;
+[heading Return Value]
+
+The allowed maximum of the sum of the sizes of the input sequence and output sequence.
+
+
+
[endsect]
[section:mutable_buffers_type basic_streambuf::mutable_buffers_type]
-[indexterm2 mutable_buffers_type..basic_streambuf] The type used to represent the put area as a list of buffers.
+[indexterm2 mutable_buffers_type..basic_streambuf] The type used to represent the output sequence as a list of buffers.
typedef implementation_defined mutable_buffers_type;
@@ -26489,12 +26591,14 @@
[section:overflow basic_streambuf::overflow]
-[indexterm2 overflow..basic_streambuf]
+[indexterm2 overflow..basic_streambuf] Override std::streambuf behaviour.
int_type overflow(
int_type c);
+Behaves according to the specification of `std::streambuf::overflow()`, with the specialisation that `std::length_error` is thrown if appending the character to the input sequence would require the condition `size() > max_size()` to be true.
+
[endsect]
@@ -26502,10 +26606,31 @@
[section:prepare basic_streambuf::prepare]
-[indexterm2 prepare..basic_streambuf] Get a list of buffers that represents the put area, with the given size.
+[indexterm2 prepare..basic_streambuf] Get a list of buffers that represents the output sequence, with the given size.
mutable_buffers_type prepare(
- std::size_t size);
+ std::size_t n);
+
+
+Ensures that the output sequence can accommodate `n` characters, reallocating character array objects as necessary.
+
+
+[heading Return Value]
+
+An object of type `mutable_buffers_type` that satisfies MutableBufferSequence requirements, representing character array objects at the start of the output sequence such that the sum of the buffer sizes is `n`.
+
+[heading Exceptions]
+
+
+[variablelist
+
+[[std::length_error][If `size() + n > max_size()`.]]
+
+]
+
+[heading Remarks]
+
+The returned object is invalidated by any `basic_streambuf` member function that modifies the input sequence or output sequence.
@@ -26528,23 +26653,43 @@
[section:size basic_streambuf::size]
-[indexterm2 size..basic_streambuf] Return the size of the get area in characters.
+[indexterm2 size..basic_streambuf] Get the size of the input sequence.
std::size_t size() const;
+[heading Return Value]
+
+The size of the input sequence. The value is equal to that calculated for `s` in the following code:
+
+ size_t s = 0;
+ const_buffers_type bufs = data();
+ const_buffers_type::const_iterator i = bufs.begin();
+ while (i != bufs.end())
+ {
+ const_buffer buf(*i++);
+ s += buffer_size(buf);
+ }
+
+
+
+
+
+
[endsect]
[section:underflow basic_streambuf::underflow]
-[indexterm2 underflow..basic_streambuf]
+[indexterm2 underflow..basic_streambuf] Override std::streambuf behaviour.
int_type underflow();
+Behaves according to the specification of `std::streambuf::underflow()`.
+
[endsect]
@@ -56141,14 +56286,14 @@
[
[[link boost_asio.reference.basic_streambuf.const_buffers_type [*const_buffers_type]]]
- [The type used to represent the get area as a list of buffers. ]
+ [The type used to represent the input sequence as a list of buffers. ]
]
[
[[link boost_asio.reference.basic_streambuf.mutable_buffers_type [*mutable_buffers_type]]]
- [The type used to represent the put area as a list of buffers. ]
+ [The type used to represent the output sequence as a list of buffers. ]
]
@@ -56160,37 +56305,37 @@
[
[[link boost_asio.reference.basic_streambuf.basic_streambuf [*basic_streambuf]]]
- [Construct a buffer with a specified maximum size. ]
+ [Construct a basic_streambuf object. ]
]
[
[[link boost_asio.reference.basic_streambuf.commit [*commit]]]
- [Move the start of the put area by the specified number of characters. ]
+ [Move characters from the output sequence to the input sequence. ]
]
[
[[link boost_asio.reference.basic_streambuf.consume [*consume]]]
- [Move the start of the get area by the specified number of characters. ]
+ [Remove characters from the input sequence. ]
]
[
[[link boost_asio.reference.basic_streambuf.data [*data]]]
- [Get a list of buffers that represents the get area. ]
+ [Get a list of buffers that represents the input sequence. ]
]
[
[[link boost_asio.reference.basic_streambuf.max_size [*max_size]]]
- [Return the maximum size of the buffer. ]
+ [Get the maximum size of the basic_streambuf. ]
]
[
[[link boost_asio.reference.basic_streambuf.prepare [*prepare]]]
- [Get a list of buffers that represents the put area, with the given size. ]
+ [Get a list of buffers that represents the output sequence, with the given size. ]
]
[
[[link boost_asio.reference.basic_streambuf.size [*size]]]
- [Return the size of the get area in characters. ]
+ [Get the size of the input sequence. ]
]
]
@@ -56201,7 +56346,7 @@
[
[[link boost_asio.reference.basic_streambuf.overflow [*overflow]]]
- []
+ [Override std::streambuf behaviour. ]
]
[
@@ -56211,11 +56356,67 @@
[
[[link boost_asio.reference.basic_streambuf.underflow [*underflow]]]
- []
+ [Override std::streambuf behaviour. ]
]
]
+The `basic_streambuf` class is derived from `std::streambuf` to associate the streambuf's input and output sequences with one or more character arrays. These character arrays are internal to the `basic_streambuf` object, but direct access to the array elements is provided to permit them to be used efficiently with I/O operations. Characters written to the output sequence of a `basic_streambuf` object are appended to the input sequence of the same object.
+
+The `basic_streambuf` class's public interface is intended to permit the following implementation strategies:
+
+
+* A single contiguous character array, which is reallocated as necessary to accommodate changes in the size of the character sequence. This is the implementation approach currently used in Asio.
+
+* A sequence of one or more character arrays, where each array is of the same size. Additional character array objects are appended to the sequence to accommodate changes in the size of the character sequence.
+
+* A sequence of one or more character arrays of varying sizes. Additional character array objects are appended to the sequence to accommodate changes in the size of the character sequence.
+
+The constructor for basic_streambuf accepts a `size_t` argument specifying the maximum of the sum of the sizes of the input sequence and output sequence. During the lifetime of the `basic_streambuf` object, the following invariant holds:
+
+ size() <= max_size()
+
+
+Any member function that would, if successful, cause the invariant to be violated shall throw an exception of class `std::length_error`.
+
+The constructor for `basic_streambuf` takes an Allocator argument. A copy of this argument is used for any memory allocation performed, by the constructor and by all member functions, during the lifetime of each `basic_streambuf` object.
+
+
+[heading Examples]
+
+Writing directly from an streambuf to a socket:
+
+ boost::asio::streambuf b;
+ std::ostream os(&b);
+ os << "Hello, World!\n";
+
+ // try sending some data in input sequence
+ size_t n = sock.send(b.data());
+
+ b.consume(n); // sent data is removed from input sequence
+
+
+
+
+Reading from a socket directly into a streambuf:
+
+ boost::asio::streambuf b;
+
+ // reserve 512 bytes in output sequence
+ boost::asio::streambuf::const_buffers_type bufs = b.prepare(512);
+
+ size_t n = sock.receive(bufs);
+
+ // received data is "committed" from output sequence to input sequence
+ b.commit(n);
+
+ std::istream is(&b);
+ std::string s;
+ is >> s;
+
+
+
+
[endsect]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk