More overview.

asio/src/doc/overview.qbk

@@ -14,8 +14,7 @@
   * [link asio.overview.core.strands Strands: Use Threads Without Explicit Locking]
   * [link asio.overview.core.buffers Buffers]
   * Facilities for managing short reads/writes
-  * Addition of new services
-  * null_buffers reactor-style
+  * [link asio.overview.core.reactor Reactor-Style Operations]
   * [link asio.overview.core.line_based Line-Based Operations]
   * [link asio.overview.core.allocation Custom Memory Allocation]
 * [link asio.overview.networking Networking]
@@ -46,6 +45,7 @@
 [include overview/threads.qbk]
 [include overview/strands.qbk]
 [include overview/buffers.qbk]
+[include overview/reactor.qbk]
 [include overview/line_based.qbk]
 [include overview/allocation.qbk]
 [include overview/eof.qbk]

asio/src/doc/overview/buffers.qbk

@@ -56,6 +56,54 @@ into a container. The `MutableBufferSequence` and `ConstBufferSequence`
 concepts have been defined so that containers such as `std::vector`,
 `std::list`, `std::vector` or `boost::array` can be used.
 
+[heading Streambuf for Integration with Iostreams]
+
+The class `asio::basic_streambuf` is derived from `std::basic_streambuf` to
+associate the input sequence and output sequence with one or more objects of
+some character array type, whose elements store arbitrary values. These
+character array objects are internal to the streambuf object, but direct access
+to the array elements is provided to permit them to be used with I/O
+operations, such as the send or receive operations of a socket:
+
+* The input sequence of the streambuf is accessible via the [link
+  asio.reference.basic_streambuf.data data()] member function. The return type
+  of this function meets the `ConstBufferSequence` requirements.
+
+* The output sequence of the streambuf is accessible via the [link
+  asio.reference.basic_streambuf.data prepare()] member function. The return
+  type of this function meets the `MutableBufferSequence` requirements.
+
+* Data is transferred from the front of the output sequence to the back of the
+  input sequence by calling the [link asio.reference.basic_streambuf.commmit
+  commit()] member function.
+
+* Data is removed from the front of the input sequence by calling the [link
+  asio.reference.basic_streambuf.consume consume()] member function.
+
+The streambuf constructor accepts a `size_t` argument specifying the maximum of
+the sum of the sizes of the input sequence and output sequence. Any operation
+that would, if successful, grow the internal data beyond this limit will throw
+a `std::length_error` exception.
+
+[heading Bytewise Traversal of Buffer Sequences]
+
+The `buffers_iterator<>` class template allows buffer sequences (i.e. types
+meeting `MutableBufferSequence` or `ConstBufferSequence` requirements) to be
+traversed as though they were a contiguous sequence of bytes. Helper functions
+called buffers_begin() and buffers_end() are also provided, where the
+buffers_iterator<> template parameter is automatically deduced.
+
+As an example, to read a single line from a socket and into a `std::string`,
+you may write:
+
+  asio::streambuf sb;
+  ...
+  std::size_t n = asio::read_until(sock, sb, '\n');
+  asio::streambuf::const_buffers_type bufs = sb.data();
+  std::string line(
+      asio::buffers_begin(bufs),
+      asio::buffers_begin(bufs) + n);
+
 [heading Buffer Debugging]
 
 Some standard library implementations, such as the one that ships with
@@ -99,10 +147,14 @@ It can also be explicitly disabled by defining `ASIO_DISABLE_BUFFER_DEBUGGING`.
 [heading See Also]
 
 [link asio.reference.buffer buffer],
+[link asio.reference.buffers_begin buffers_begin],
+[link asio.reference.buffers_end buffers_end],
+[link asio.reference.buffers_iterator buffers_iterator],
 [link asio.reference.const_buffer const_buffer],
 [link asio.reference.const_buffers_1 const_buffers_1],
 [link asio.reference.mutable_buffer mutable_buffer],
-[link asio.reference.const_buffers_1 mutable_buffers_1],
+[link asio.reference.mutable_buffers_1 mutable_buffers_1],
+[link asio.reference.streambuf streambuf],
 [link asio.reference.ConstBufferSequence ConstBufferSequence],
 [link asio.reference.MutableBufferSequence MutableBufferSequence],
 [link asio.examples.buffers buffers example].

asio/src/doc/overview/line_based.qbk

@@ -9,11 +9,9 @@
 
 Many commonly-used internet protocols are line-based, which means that they
 have protocol elements that are delimited by the character sequence `"\r\n"`.
-Examples include HTTP, SMTP and FTP.
-
-To more easily permit the implementation of line-based protocols, as well as
-other protocols that use delimiters, Asio includes the functions
-`read_until()` and `async_read_until()`.
+Examples include HTTP, SMTP and FTP. To more easily permit the implementation
+of line-based protocols, as well as other protocols that use delimiters, Asio
+includes the functions `read_until()` and `async_read_until()`.
 
 The following example illustrates the use of `async_read_until()` in an HTTP
 server, to receive the first line of an HTTP request from a client:
@@ -47,4 +45,74 @@ server, to receive the first line of an HTTP request from a client:
     asio::streambuf data_;
   };
 
+The `streambuf` data member serves as a place to store the data that has been
+read from the socket before it is searched for the delimiter. It is important
+to remember that there may be additional data ['after] the delimiter. This
+surplus data should be left in the `streambuf` so that it may be inspected by a
+subsequent call to `read_until()` or `async_read_until()`.
+
+The delimiters may be specified as a single `char`, a `std::string` or a
+`boost::regex`. The `read_until()` and `async_read_until()` functions also
+include overloads that accept a user-defined function object called a match
+condition. For example, to read data into a streambuf until whitespace is
+encountered:
+
+  typedef asio::buffers_iterator<
+      asio::streambuf::const_buffers_type> iterator;
+
+  std::pair<iterator, bool>
+  match_whitespace(iterator begin, iterator end)
+  {
+    iterator i = begin;
+    while (i != end)
+      if (std::isspace(*i++))
+        return std::make_pair(i, true);
+    return std::make_pair(i, false);
+  }
+  ...
+  asio::streambuf b;
+  asio::read_until(s, b, match_whitespace);
+
+To read data into a streambuf until a matching character is found:
+
+  class match_char
+  {
+  public:
+    explicit match_char(char c) : c_(c) {}
+
+    template <typename Iterator>
+    std::pair<Iterator, bool> operator()(
+        Iterator begin, Iterator end) const
+    {
+      Iterator i = begin;
+      while (i != end)
+        if (c_ == *i++)
+          return std::make_pair(i, true);
+      return std::make_pair(i, false);
+    }
+
+  private:
+    char c_;
+  };
+
+  namespace asio {
+    template <> struct is_match_condition<match_char>
+      : public boost::true_type {};
+  } // namespace asio
+  ...
+  asio::streambuf b;
+  asio::read_until(s, b, match_char('a'));
+
+The `is_match_condition<>` type trait automatically evaluates to true for
+functions, and for function objects with a nested `result_type` typedef. For
+other types the trait must be explicitly specialised, as shown above.
+
+[heading See Also]
+
+[link asio.reference.async_read_until async_read_until()],
+[link asio.reference.is_match_condition is_match_condition],
+[link asio.reference.read_until read_until()],
+[link asio.reference.streambuf streambuf],
+[link asio.examples.http_client HTTP client example].
+
 [endsect]

asio/src/doc/overview/reactor.qbk

@@ -0,0 +1,43 @@
+[/
+ / Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:reactor Reactor-Style Operations]
+
+Sometimes a program must be integrated with a third-party library that wants to
+perform the I/O operations itself. To facilitate this, Asio includes a
+`null_buffers` type that can be used with both read and write operations. A
+`null_buffers` operation doesn't return until the I/O object is "ready" to
+perform the operation.
+
+As an example, to perform a non-blocking read something like the
+following may be used:
+
+  ip::tcp::socket socket(my_io_service);
+  ...
+  ip::tcp::socket::non_blocking nb(true);
+  socket.io_control(nb);
+  ...
+  socket.async_read_some(null_buffers(), read_handler);
+  ...
+  void read_handler(error_code ec)
+  {
+    if (!ec)
+    {
+      std::vector<char> buf(socket.available());
+      socket.read_some(buffer(buf));
+    }
+  }
+  
+These operations are supported for sockets on all platforms, and for the POSIX
+stream-oriented descriptor classes.
+
+[heading See Also]
+
+[link asio.reference.null_buffers null_buffers],
+[link asio.examples.nonblocking nonblocking example].
+
+[endsect]