More overview.

asio/src/doc/overview.qbk

@@ -12,14 +12,13 @@
   * [link asio.overview.core.async The Proactor Design Pattern: Concurrency Without Threads]
   * [link asio.overview.core.threads Threads and Asio]
   * [link asio.overview.core.strands Strands: Use Threads Without Explicit Locking]
-  * Buffer management
-  * Scatter-gather
+  * [link asio.overview.core.buffers Buffers]
   * Facilities for managing short reads/writes
   * Addition of new services
   * null_buffers reactor-style
   * [link asio.overview.core.line_based Line-Based Operations]
   * [link asio.overview.core.allocation Custom Memory Allocation]
-* Networking
+* [link asio.overview.networking Networking]
   * [link asio.overview.networking.iostreams Socket Iostreams]
   * [link asio.overview.networking.bsd_sockets The BSD Socket API and Asio]
   * IPv4 and IPv6 independence
@@ -28,8 +27,7 @@
   * Multicast
   * Raw sockets
   * ICMP
-* Timers
-  * Customisable time sources
+* [link asio.overview.timers Timers]
 * [link asio.overview.serial_ports Serial Ports]
 * [link asio.overview.posix POSIX-Specific Functionality]
   * [link asio.overview.posix.local UNIX Domain Sockets]
@@ -61,6 +59,7 @@
 
 [endsect]
 
+[include overview/timers.qbk]
 [include overview/serial_ports.qbk]
 [include overview/posix.qbk]
 [include overview/windows.qbk]

asio/src/doc/overview/buffers.qbk

@@ -7,9 +7,11 @@
 
 [section:buffers Buffers]
 
-To allow the development of efficient network applications, Asio includes
-support for scatter-gather operations. These operations involve one or more
-buffers (where each buffer is a contiguous region of memory):
+Fundamentally, I/O involves the transfer of data to and from contiguous regions
+of memory, called buffers. These buffers can be simply expressed as a tuple
+consisting of a pointer and a size in bytes. However, to allow the development
+of efficient network applications, Asio includes support for scatter-gather
+operations. These operations involve one or more buffers:
 
 * A scatter-read receives data into multiple buffers.
 * A gather-write transmits multiple buffers.
@@ -19,11 +21,10 @@ approach used in Asio is to define a type (actually two types) to
 represent a single buffer. These can be stored in a container, which may be
 passed to the scatter-gather operations.
 
-A buffer, as a contiguous region of memory, can be represented by an address
-and size in bytes. There is a distinction between modifiable memory (called
-mutable in Asio) and non-modifiable memory (where the latter is
-created from the storage for a const-qualified variable). These two types could
-therefore be defined as follows:
+In addition to specifying buffers as a pointer and size in bytes, Asio makes a
+distinction between modifiable memory (called mutable) and non-modifiable
+memory (where the latter is created from the storage for a const-qualified
+variable). These two types could therefore be defined as follows:
 
   typedef std::pair<void*, std::size_t> mutable_buffer;
   typedef std::pair<const void*, std::size_t> const_buffer;
@@ -31,7 +32,7 @@ therefore be defined as follows:
 Here, a mutable_buffer would be convertible to a const_buffer, but conversion
 in the opposite direction is not valid.
 
-However, Asio does not use the above definitions, but instead defines two
+However, Asio does not use the above definitions as-is, but instead defines two
 classes: `mutable_buffer` and `const_buffer`. The goal of these is to provide
 an opaque representation of contiguous memory, where:
 
@@ -55,4 +56,55 @@ 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 Buffer Debugging]
+
+Some standard library implementations, such as the one that ships with
+Microsoft Visual C++ 8.0 and later, provide a feature called iterator
+debugging. What this means is that the validity of iterators is checked at
+runtime. If a program tries to use an iterator that has been invalidated, an
+assertion will be triggered. For example:
+
+  std::vector<int> v(1)
+  std::vector<int>::iterator i = v.begin();
+  v.clear(); // invalidates iterators
+  *i = 0; // assertion!
+
+Asio takes advantage of this feature to add buffer debugging. Consider the
+following code:
+
+  void dont_do_this()
+  {
+   std::string msg = "Hello, world!";
+   asio::async_write(sock, asio::buffer(msg), my_handler);
+  }
+
+When you call an asynchronous read or write you need to ensure that the buffers
+for the operation are valid until the completion handler is called. In the
+above example, the buffer is the `std::string` variable `msg`. This variable is
+on the stack, and so it goes out of scope before the asynchronous operation
+completes. If you're lucky then the application will crash, but random failures
+are more likely.
+
+When buffer debugging is enabled, Asio stores an iterator into the string until
+the asynchronous operation completes, and then dereferences it to check its
+validity. In the above example you would observe an assertion failure just
+before Asio tries to call the completion handler.
+
+This feature is automatically made available for Microsoft Visual Studio 8.0 or
+later and for GCC when `_GLIBCXX_DEBUG` is defined. There is a performance cost
+to this checking, so buffer debugging is only enabled in debug builds. For
+other compilers it may be enabled by defining `ASIO_ENABLE_BUFFER_DEBUGGING`.
+It can also be explicitly disabled by defining `ASIO_DISABLE_BUFFER_DEBUGGING`.
+
+[heading See Also]
+
+[link asio.reference.buffer buffer],
+[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.ConstBufferSequence ConstBufferSequence],
+[link asio.reference.MutableBufferSequence MutableBufferSequence],
+[link asio.examples.buffers buffers example].
+
 [endsect]

asio/src/doc/overview/posix.qbk

@@ -46,7 +46,7 @@ A client that connects to this server might look like:
 Transmission of file descriptors or credentials across UNIX domain sockets is
 not directly supported within Asio, but may be achieved by accessing the
 socket's underlying descriptor using the [link
-asio.reference.basic_socket.native `native()`] member function.
+asio.reference.basic_socket.native native()] member function.
 
 [heading See Also]
 
@@ -85,10 +85,10 @@ and output, the following objects may be created:
 
 These are then used as synchronous or asynchronous read and write streams. This
 means the objects can be used with any of the [link asio.reference.read
-`read()`], [link asio.reference.async_read `async_read()`], [link
-asio.reference.write `write()`], [link asio.reference.async_write
-`async_write()`], [link asio.reference.read_until `read_until()`] or [link
-asio.reference.async_read_until `async_read_until()`] free functions.
+read()], [link asio.reference.async_read async_read()], [link
+asio.reference.write write()], [link asio.reference.async_write async_write()],
+[link asio.reference.read_until read_until()] or [link
+asio.reference.async_read_until async_read_until()] free functions.
 
 [heading See Also]
 

asio/src/doc/overview/serial_ports.qbk

@@ -16,11 +16,11 @@ where name is something like `"COM1"` on Windows, and `"/dev/ttyS0"` on POSIX
 platforms.
 
 Once opened the serial port may be used as a stream. This means the objects can
-be used with any of the [link asio.reference.read `read()`], [link
-asio.reference.async_read `async_read()`], [link asio.reference.write
-`write()`], [link asio.reference.async_write `async_write()`], [link
-asio.reference.read_until `read_until()`] or [link
-asio.reference.async_read_until `async_read_until()`] free functions.
+be used with any of the [link asio.reference.read read()], [link
+asio.reference.async_read async_read()], [link asio.reference.write write()],
+[link asio.reference.async_write async_write()], [link
+asio.reference.read_until read_until()] or [link
+asio.reference.async_read_until async_read_until()] free functions.
 
 The serial port implementation also includes option classes for configuring the
 port's baud rate, flow control type, parity, stop bits and character size.

asio/src/doc/overview/timers.qbk

@@ -0,0 +1,53 @@
+[/
+ / 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:timers Timers]
+
+Long running I/O operations will often have a deadline by which they must have
+completed. These deadlines may be expressed as absolute times, but are often be
+calculated relative to the current time.
+
+As a simple example, to perform a synchronous wait operation on a timer using a
+relative time one may write:
+
+  io_service i;
+  ...
+  deadline_timer t(i);
+  t.expires_from_now(boost::posix_time::seconds(5));
+  t.wait();
+
+More commonly, a program will perform an asynchronous wait operation on a
+timer:
+
+  void handler(error_code ec) { ... }
+  ...
+  io_service i;
+  ...
+  deadline_timer t(i);
+  t.expires_from_now(boost::posix_time::milliseconds(400));
+  t.async_wait(handler);
+  ...
+  i.run();
+
+The deadline associated with a timer may be also be obtained as a relative time:
+
+  boost::posix_time::time_duration time_until_expiry
+    = t.expires_from_now();
+
+or as an absolute time to allow composition of timers:
+
+  deadline_timer t2(i);
+  t2.expires_at(t.expires_at() + boost::posix_time::seconds(30));
+
+[heading See Also]
+
+[link asio.reference.basic_deadline_timer basic_deadline_timer],
+[link asio.reference.deadline_timer deadline_timer],
+[link asio.reference.deadline_timer_service deadline_timer_service],
+[link asio.tutorial.tuttimer1 timer tutorials].
+
+[endsect]

asio/src/doc/overview/windows.qbk

@@ -24,10 +24,10 @@ object may be created:
 
 These are then used as synchronous or asynchronous read and write streams. This
 means the objects can be used with any of the [link asio.reference.read
-`read()`], [link asio.reference.async_read `async_read()`], [link
-asio.reference.write `write()`], [link asio.reference.async_write
-`async_write()`], [link asio.reference.read_until `read_until()`] or [link
-asio.reference.async_read_until `async_read_until()`] free functions.
+read()], [link asio.reference.async_read async_read()], [link
+asio.reference.write write()], [link asio.reference.async_write
+async_write()], [link asio.reference.read_until read_until()] or [link
+asio.reference.async_read_until async_read_until()] free functions.
 
 The kernel object referred to by the `HANDLE` must support use with I/O
 completion ports (which means that named pipes are supported, but anonymous
@@ -66,11 +66,11 @@ Data may be read from or written to the handle using one of the
 `async_write_some_at()` member functions. However, like the equivalent
 functions (`read_some()`, etc.) on streams, these functions are only required
 to transfer one or more bytes in a single operation. Therefore free functions
-called [link asio.reference.read_at `read_at()`], [link
-asio.reference.async_read_at `async_read_at()`], [link asio.reference.write_at
-`write_at()`] and [link asio.reference.async_write_at `async_write_at()`] have
-been created to repeatedly call the corresponding [^[**]_some_at()]
-function until all data has been transferred.
+called [link asio.reference.read_at read_at()], [link
+asio.reference.async_read_at async_read_at()], [link asio.reference.write_at
+write_at()] and [link asio.reference.async_write_at async_write_at()] have been
+created to repeatedly call the corresponding [^[**]_some_at()] function until
+all data has been transferred.
 
 [heading See Also]