[Boost-commit] svn:boost r47503 - in trunk/libs/asio/doc: . design overview

From: chris_at_[hidden]
Date: 2008-07-17 11:05:26

Author: chris_kohlhoff
Date: 2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
New Revision: 47503
URL: http://svn.boost.org/trac/boost/changeset/47503

Log:
Documentation updates.

Added:
   trunk/libs/asio/doc/index.xml   (contents, props changed)
   trunk/libs/asio/doc/overview/
   trunk/libs/asio/doc/overview.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/allocation.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/async.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/bsd_sockets.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/buffers.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/implementation.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/iostreams.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/line_based.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/posix.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/proactor.dot   (contents, props changed)
   trunk/libs/asio/doc/overview/proactor.png   (contents, props changed)
   trunk/libs/asio/doc/overview/rationale.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/reactor.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/serial_ports.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/ssl.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/strands.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/streams.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/threads.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/timers.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/windows.qbk   (contents, props changed)
Removed:
   trunk/libs/asio/doc/design/
   trunk/libs/asio/doc/design.qbk
Text files modified: 
   trunk/libs/asio/doc/Jamfile.v2   |     8 ++++----                                
   trunk/libs/asio/doc/asio.qbk     |    21 +++++++++++++++------                   
   trunk/libs/asio/doc/examples.qbk |    27 +++++++++++++++++++++++++++             
   trunk/libs/asio/doc/using.qbk    |     7 +++++++                                 
   4 files changed, 53 insertions(+), 10 deletions(-)

Modified: trunk/libs/asio/doc/Jamfile.v2
==============================================================================
--- trunk/libs/asio/doc/Jamfile.v2	(original)
+++ trunk/libs/asio/doc/Jamfile.v2	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -24,14 +24,14 @@
 
 install images
   :
-    design/proactor.png
+    overview/proactor.png
   :
     <location>html/boost_asio
   ;
 
 local example-names = allocation buffers chat echo http/client http/server
-  http/server2 http/server3 invocation iostreams multicast serialization
-  services socks4 ssl timeouts timers ;
+  http/server2 http/server3 invocation iostreams local multicast nonblocking
+  porthopper serialization services socks4 ssl timeouts timers ;
 
 for local l in $(example-names)
 {
@@ -66,7 +66,7 @@
 
 install asio_doc_images
   :
-    design/proactor.png
+    overview/proactor.png
   :
     <location>$(BOOST_ROOT)/doc/html/boost_asio
   ;

Modified: trunk/libs/asio/doc/asio.qbk
==============================================================================
--- trunk/libs/asio/doc/asio.qbk	(original)
+++ trunk/libs/asio/doc/asio.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -37,13 +37,21 @@
 
 [/=============================================================================]
 
-Boost.Asio is a cross-platform C++ library for network programming that
-provides developers with a consistent asynchronous I/O model using a modern C++
-approach.
+Boost.Asio is a cross-platform C++ library for network and low-level I/O
+programming that provides developers with a consistent asynchronous model using
+a modern C++ approach.
 
 [variablelist
   [
     [
+      [link boost_asio.overview Overview]
+    ]
+    [
+      An overview of the features included in Boost.Asio, plus rationale and design information.
+    ]
+  ]
+  [
+    [
       [link boost_asio.using Using Boost.Asio]
     ]
     [
@@ -80,16 +88,17 @@
   ]
   [
     [
-      [link boost_asio.design Design]
+      [link boost_asio.index Index]
     ]
     [
-      Rationale and design information for Boost.Asio.
+      Book-style text index of Boost.Asio documentation.
     ]
   ]
 ]
 
+[include overview.qbk]
 [include using.qbk]
 [include tutorial.qbk]
 [include examples.qbk]
 [include reference.qbk]
-[include design.qbk]
+[xinclude index.xml]

Deleted: trunk/libs/asio/doc/design.qbk
==============================================================================
--- trunk/libs/asio/doc/design.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
+++ (empty file)
@@ -1,104 +0,0 @@
-[/
- / 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:design Design Notes]
-
-[variablelist
-  [
-    [
-      [link boost_asio.design.rationale Rationale]
-    ]
-    [
-      Design rationale for the Boost.Asio library.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.async Asynchronous operations]
-    ]
-    [
-      Support for asynchronous operations in the Boost.Asio library is based on
-      the Proactor pattern. This design note outlines the advantages and
-      disadvantages of this approach.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.allocation Custom memory allocation]
-    ]
-    [
-      Describes the custom memory allocation support in Boost.Asio.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.buffers Buffers]
-    ]
-    [
-      Examines the buffer abstraction used by asio in order to support
-      scatter-gather operations.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.eof Why EOF is an error]
-    ]
-    [
-      Discusses why the end-of-file condition should be an error code.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.line_based Line-based protocols]
-    ]
-    [
-      Outlines Boost.Asio's support for line-based protocols.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.threads Threads]
-    ]
-    [
-      An implementation of Boost.Asio for a particular platform may make use of
-      one or more additional threads to emulate asynchronicity. This design
-      note discusses design rules applied to the use of threads in this way.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.strands Strands]
-    ]
-    [
-      Describes the "strand" abstraction provided by Boost.Asio to ease
-      concurrent programming and provide scalability across multiple
-      processors.
-    ]
-  ]
-  [
-    [
-      [link boost_asio.design.implementation Platform-specific implementation]
-    ]
-    [
-      This design note lists platform-specific implementation details, such as
-      the default demultiplexing mechanism, the number of threads created
-      internally, and when threads are created.
-    ]
-  ]
-]
-
-[include design/rationale.qbk]
-[include design/async.qbk]
-[include design/allocation.qbk]
-[include design/buffers.qbk]
-[include design/eof.qbk]
-[include design/line_based.qbk]
-[include design/threads.qbk]
-[include design/strands.qbk]
-[include design/implementation.qbk]
-
-[endsect]

Modified: trunk/libs/asio/doc/examples.qbk
==============================================================================
--- trunk/libs/asio/doc/examples.qbk	(original)
+++ trunk/libs/asio/doc/examples.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -219,4 +219,31 @@
 * [@boost_asio/example/timers/time_t_timer.cpp]
 
 
+[heading Porthopper]
+
+Example illustrating mixed synchronous and asynchronous operations, and how to
+use Boost.Lambda with Boost.Asio.
+
+* [@boost_asio/example/porthopper/protocol.hpp]
+* [@boost_asio/example/porthopper/client.cpp]
+* [@boost_asio/example/porthopper/server.cpp]
+
+
+[heading Nonblocking]
+
+Example demonstrating reactor-style operations for integrating a third-party
+library that wants to perform the I/O operations itself.
+
+* [@boost_asio/example/nonblocking/third_party_lib.cpp]
+
+
+[heading UNIX Domain Sockets]
+
+Examples showing how to use UNIX domain (local) sockets.
+
+* [@boost_asio/example/local/connect_pair.cpp]
+* [@boost_asio/example/local/stream_server.cpp]
+* [@boost_asio/example/local/stream_client.cpp]
+
+
 [endsect]

Added: trunk/libs/asio/doc/index.xml
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/index.xml	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "../../../tools/boostbook/dtd/boostbook.dtd">
+
+<!--
+  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 id="boost_asio.index">
+  <index/>
+</section>

Added: trunk/libs/asio/doc/overview.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,81 @@
+[/
+ / 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:overview Overview]
+
+* [link boost_asio.overview.rationale Rationale]
+* [link boost_asio.overview.core Core Concepts and Functionality]
+  * [link boost_asio.overview.core.async The Proactor Design Pattern: Concurrency Without Threads]
+  * [link boost_asio.overview.core.threads Threads and Boost.Asio]
+  * [link boost_asio.overview.core.strands Strands: Use Threads Without Explicit Locking]
+  * [link boost_asio.overview.core.buffers Buffers]
+  * [link boost_asio.overview.core.streams Streams, Short Reads and Short Writes]
+  * [link boost_asio.overview.core.reactor Reactor-Style Operations]
+  * [link boost_asio.overview.core.line_based Line-Based Operations]
+  * [link boost_asio.overview.core.allocation Custom Memory Allocation]
+* [link boost_asio.overview.networking Networking]
+  * [link boost_asio.overview.networking.iostreams Socket Iostreams]
+  * [link boost_asio.overview.networking.bsd_sockets The BSD Socket API and Boost.Asio]
+  [/ * IPv4 and IPv6 independence
+  * TCP
+  * UDP
+  * Multicast
+  * Raw sockets
+  * ICMP ]
+* [link boost_asio.overview.timers Timers]
+* [link boost_asio.overview.serial_ports Serial Ports]
+* [link boost_asio.overview.posix POSIX-Specific Functionality]
+  * [link boost_asio.overview.posix.local UNIX Domain Sockets]
+  * [link boost_asio.overview.posix.stream_descriptor Stream-Oriented File Descriptors]
+* [link boost_asio.overview.windows Windows-Specific Functionality]
+  * [link boost_asio.overview.windows.stream_handle Stream-Oriented HANDLEs]
+  * [link boost_asio.overview.windows.random_access_handle Random-Access HANDLEs]
+* [link boost_asio.overview.ssl SSL]
+* [link boost_asio.overview.implementation Platform-Specific Implementation Notes]
+
+[include overview/rationale.qbk]
+
+[section:core Core Concepts and Functionality]
+
+* [link boost_asio.overview.core.async The Proactor Design Pattern: Concurrency Without Threads]
+* [link boost_asio.overview.core.threads Threads and Boost.Asio]
+* [link boost_asio.overview.core.strands Strands: Use Threads Without Explicit Locking]
+* [link boost_asio.overview.core.buffers Buffers]
+* [link boost_asio.overview.core.streams Streams, Short Reads and Short Writes]
+* [link boost_asio.overview.core.reactor Reactor-Style Operations]
+* [link boost_asio.overview.core.line_based Line-Based Operations]
+* [link boost_asio.overview.core.allocation Custom Memory Allocation]
+
+[include overview/async.qbk]
+[include overview/threads.qbk]
+[include overview/strands.qbk]
+[include overview/buffers.qbk]
+[include overview/streams.qbk]
+[include overview/reactor.qbk]
+[include overview/line_based.qbk]
+[include overview/allocation.qbk]
+
+[endsect]
+
+[section:networking Networking]
+
+* [link boost_asio.overview.networking.iostreams Socket Iostreams]
+* [link boost_asio.overview.networking.bsd_sockets The BSD Socket API and Boost.Asio]
+
+[include overview/iostreams.qbk]
+[include overview/bsd_sockets.qbk]
+
+[endsect]
+
+[include overview/timers.qbk]
+[include overview/serial_ports.qbk]
+[include overview/posix.qbk]
+[include overview/windows.qbk]
+[include overview/ssl.qbk]
+[include overview/implementation.qbk]
+
+[endsect]

Added: trunk/libs/asio/doc/overview/allocation.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/allocation.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,67 @@
+[/
+ / 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:allocation Custom Memory Allocation]
+
+Many asynchronous operations need to allocate an object to store state
+associated with the operation. For example, a Win32 implementation needs
+`OVERLAPPED`-derived objects to pass to Win32 API functions.
+
+Furthermore, programs typically contain easily identifiable chains of
+asynchronous operations. A half duplex protocol implementation (e.g. an HTTP
+server) would have a single chain of operations per client (receives followed
+by sends). A full duplex protocol implementation would have two chains
+executing in parallel. Programs should be able to leverage this knowledge to
+reuse memory for all asynchronous operations in a chain.
+
+Given a copy of a user-defined `Handler` object `h`, if the implementation
+needs to allocate memory associated with that handler it will execute the code:
+
+  void* pointer = asio_handler_allocate(size, &h);
+
+Similarly, to deallocate the memory it will execute:
+
+  asio_handler_deallocate(pointer, size, &h);
+
+These functions are located using argument-dependent lookup. The implementation
+provides default implementations of the above functions in the `asio` namespace:
+
+  void* asio_handler_allocate(size_t, ...);
+  void asio_handler_deallocate(void*, size_t, ...);
+
+which are implemented in terms of `::operator new()` and `::operator delete()`
+respectively.
+
+The implementation guarantees that the deallocation will occur before the
+associated handler is invoked, which means the memory is ready to be reused for
+any new asynchronous operations started by the handler.
+
+The custom memory allocation functions may be called from any user-created
+thread that is calling a library function. The implementation guarantees that,
+for the asynchronous operations included the library, the implementation will
+not make concurrent calls to the memory allocation functions for that handler.
+The implementation will insert appropriate memory barriers to ensure correct
+memory visibility should allocation functions need to be called from different
+threads.
+
+Custom memory allocation support is currently implemented for all asynchronous
+operations with the following exceptions:
+
+* `ip::basic_resolver::async_resolve()` on all platforms.
+
+* `basic_socket::async_connect()` on Windows.
+
+* Any operation involving `null_buffers()` on Windows, other than an
+  asynchronous read performed on a stream-oriented socket.
+
+[heading See Also]
+
+[link boost_asio.reference.asio_handler_allocate asio_handler_allocate],
+[link boost_asio.reference.asio_handler_deallocate asio_handler_deallocate],
+[link boost_asio.examples.allocation custom memory allocation example].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/async.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/async.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,185 @@
+[/
+ / 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:async The Proactor Design Pattern: Concurrency Without Threads]
+
+The Boost.Asio library offers side-by-side support for synchronous and asynchronous
+operations. The asynchronous support is based on the Proactor design pattern
+[link boost_asio.overview.core.async.references \[POSA2\]]. The advantages and
+disadvantages of this approach, when compared to a synchronous-only or Reactor
+approach, are outlined below.
+
+[heading Proactor and Boost.Asio]
+
+Let us examine how the Proactor design pattern is implemented in Boost.Asio,
+without reference to platform-specific details.
+
+[$boost_asio/proactor.png]
+
+[*Proactor design pattern (adapted from \[POSA2\])]
+
+[mdash] Asynchronous Operation
+
+[:Defines an operation that is executed asynchronously, such as an asynchronous
+read or write on a socket.]
+
+[mdash] Asynchronous Operation Processor
+
+[:Executes asynchronous operations and queues events on a completion event
+queue when operations complete. From a high-level point of view, services like
+`stream_socket_service` are asynchronous operation processors.]
+
+[mdash] Completion Event Queue
+
+[:Buffers completion events until they are dequeued by an asynchronous event
+demultiplexer.]
+
+[mdash] Completion Handler
+
+[:Processes the result of an asynchronous operation. These are function
+objects, often created using `boost::bind`.]
+
+[mdash] Asynchronous Event Demultiplexer
+
+[:Blocks waiting for events to occur on the completion event queue, and returns
+a completed event to its caller.]
+
+[mdash] Proactor
+
+[:Calls the asynchronous event demultiplexer to dequeue events, and dispatches
+the completion handler (i.e. invokes the function object) associated with the
+event. This abstraction is represented by the `io_service` class.]
+
+[mdash] Initiator
+
+[:Application-specific code that starts asynchronous operations. The initiator
+interacts with an asynchronous operation processor via a high-level interface
+such as `basic_stream_socket`, which in turn delegates to a service like
+`stream_socket_service`.]
+
+[heading Implementation Using Reactor]
+
+On many platforms, Boost.Asio implements the Proactor design pattern in terms
+of a Reactor, such as `select`, `epoll` or `kqueue`. This implementation
+approach corresponds to the Proactor design pattern as follows:
+
+[mdash] Asynchronous Operation Processor
+
+[:A reactor implemented using `select`, `epoll` or `kqueue`. When the reactor
+indicates that the resource is ready to perform the operation, the processor
+executes the asynchronous operation and enqueues the associated completion
+handler on the completion event queue.]
+
+[mdash] Completion Event Queue
+
+[:A linked list of completion handlers (i.e. function objects).]
+
+[mdash] Asynchronous Event Demultiplexer
+
+[:This is implemented by waiting on an event or condition variable until a
+completion handler is available in the completion event queue.]
+
+[heading Implementation Using Windows Overlapped I/O]
+
+On Windows NT, 2000 and XP, Boost.Asio takes advantage of overlapped I/O to
+provide an efficient implementation of the Proactor design pattern. This
+implementation approach corresponds to the Proactor design pattern as follows:
+
+[mdash] Asynchronous Operation Processor
+
+[:This is implemented by the operating system. Operations are initiated by
+calling an overlapped function such as `AcceptEx`.]
+
+[mdash] Completion Event Queue
+
+[:This is implemented by the operating system, and is associated with an I/O
+completion port. There is one I/O completion port for each `io_service`
+instance.]
+
+[mdash] Asynchronous Event Demultiplexer
+
+[:Called by Boost.Asio to dequeue events and their associated completion
+handlers.]
+
+[heading Advantages] 
+
+[mdash] Portability.
+
+[:Many operating systems offer a native asynchronous I/O API (such as
+overlapped I/O on __Windows__) as the preferred option for developing high
+performance network applications. The library may be implemented in terms of
+native asynchronous I/O. However, if native support is not available, the
+library may also be implemented using synchronous event demultiplexors that
+typify the Reactor pattern, such as __POSIX__ `select()`.]
+
+[mdash] Decoupling threading from concurrency.
+
+[:Long-duration operations are performed asynchronously by the implementation
+on behalf of the application. Consequently applications do not need to spawn
+many threads in order to increase concurrency.]
+
+[mdash] Performance and scalability.
+
+[:Implementation strategies such as thread-per-connection (which a
+synchronous-only approach would require) can degrade system performance, due to
+increased context switching, synchronisation and data movement among CPUs. With
+asynchronous operations it is possible to avoid the cost of context switching
+by minimising the number of operating system threads [mdash] typically a
+limited resource [mdash] and only activating the logical threads of control
+that have events to process.]
+
+[mdash] Simplified application synchronisation.
+
+[:Asynchronous operation completion handlers can be written as though they
+exist in a single-threaded environment, and so application logic can be
+developed with little or no concern for synchronisation issues.]
+
+[mdash] Function composition.
+
+[:Function composition refers to the implementation of functions to provide a
+higher-level operation, such as sending a message in a particular format. Each
+function is implemented in terms of multiple calls to lower-level read or write
+operations.]
+
+[:For example, consider a protocol where each message consists of a
+fixed-length header followed by a variable length body, where the length of the
+body is specified in the header. A hypothetical read_message operation could be
+implemented using two lower-level reads, the first to receive the header and,
+once the length is known, the second to receive the body.]
+
+[:To compose functions in an asynchronous model, asynchronous operations can be
+chained together. That is, a completion handler for one operation can initiate
+the next. Starting the first call in the chain can be encapsulated so that the
+caller need not be aware that the higher-level operation is implemented as a
+chain of asynchronous operations.]
+
+[:The ability to compose new operations in this way simplifies the development
+of higher levels of abstraction above a networking library, such as functions
+to support a specific protocol.]
+
+[heading Disadvantages] 
+
+[mdash] Program complexity.
+
+[:It is more difficult to develop applications using asynchronous mechanisms
+due to the separation in time and space between operation initiation and
+completion. Applications may also be harder to debug due to the inverted flow
+of control.]
+
+[mdash] Memory usage.
+
+[:Buffer space must be committed for the duration of a read or write operation,
+which may continue indefinitely, and a separate buffer is required for each
+concurrent operation. The Reactor pattern, on the other hand, does not require
+buffer space until a socket is ready for reading or writing.]
+
+[heading References]
+
+\[POSA2\] D. Schmidt et al, ['Pattern Oriented Software Architecture, Volume
+2]. Wiley, 2000.
+
+[endsect]

Added: trunk/libs/asio/doc/overview/bsd_sockets.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/bsd_sockets.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,270 @@
+[/
+ / 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:bsd_sockets The BSD Socket API and Boost.Asio]
+
+The Boost.Asio library includes a low-level socket interface based on the BSD socket
+API, which is widely implemented and supported by extensive literature. It is
+also used as the basis for networking APIs in other languages, like Java. This
+low-level interface is designed to support the development of efficient and
+scalable applications. For example, it permits programmers to exert finer
+control over the number of system calls, avoid redundant data copying, minimise
+the use of resources like threads, and so on.
+
+Unsafe and error prone aspects of the BSD socket API not included. For example,
+the use of `int` to represent all sockets lacks type safety. The socket
+representation in Boost.Asio uses a distinct type for each protocol, e.g. for TCP one
+would use `ip::tcp::socket`, and for UDP one uses `ip::udp::socket`.
+
+The following table shows the mapping between the BSD socket API and Boost.Asio:
+
+[table
+  [
+    [BSD Socket API Elements]
+    [Equivalents in Boost.Asio]
+  ]
+  [
+    [socket descriptor - `int` (POSIX) or `SOCKET` (Windows)]
+    [ For TCP: [link boost_asio.reference.ip__tcp.socket ip::tcp::socket],
+               [link boost_asio.reference.ip__tcp.acceptor ip::tcp::acceptor]
+
+      For UDP: [link boost_asio.reference.ip__udp.socket ip::udp::socket]
+
+               [link boost_asio.reference.basic_socket basic_socket],
+               [link boost_asio.reference.basic_stream_socket basic_stream_socket],
+               [link boost_asio.reference.basic_datagram_socket basic_datagram_socket],
+               [link boost_asio.reference.basic_raw_socket basic_raw_socket] ]
+  ]
+  [
+    [`in_addr`,
+     `in6_addr`]
+    [          [link boost_asio.reference.ip__address ip::address],
+               [link boost_asio.reference.ip__address ip::address_v4],
+               [link boost_asio.reference.ip__address ip::address_v6] ]
+  ]
+  [
+    [`sockaddr_in`,
+     `sockaddr_in6`]
+    [ For TCP: [link boost_asio.reference.ip__tcp.endpoint ip::tcp::endpoint]
+    
+      For UDP: [link boost_asio.reference.ip__udp.endpoint ip::udp::endpoint]
+
+               [link boost_asio.reference.ip__basic_endpoint ip::basic_endpoint] ]
+  ]
+  [
+    [`accept()`]
+    [ For TCP: [link boost_asio.reference.basic_socket_acceptor.accept ip::tcp::acceptor::accept()]
+
+               [link boost_asio.reference.basic_socket_acceptor.accept basic_socket_acceptor::accept()] ]
+  ]
+  [
+    [`bind()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.bind ip::tcp::acceptor::bind()],
+               [link boost_asio.reference.basic_socket.bind ip::tcp::socket::bind()]
+
+      For UDP: [link boost_asio.reference.basic_socket.bind ip::udp::socket::bind()]
+
+               [link boost_asio.reference.basic_socket.bind basic_socket::bind()] ]
+  ]
+  [
+    [`close()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.close ip::tcp::acceptor::close()],
+               [link boost_asio.reference.basic_socket.close ip::tcp::socket::close()]
+
+      For UDP: [link boost_asio.reference.basic_socket.close ip::udp::socket::close()]
+
+               [link boost_asio.reference.basic_socket.close basic_socket::close()] ]
+  ]
+  [
+    [`connect()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.connect ip::tcp::socket::connect()]
+
+      For UDP: [link boost_asio.reference.basic_socket.connect ip::udp::socket::connect()]
+
+               [link boost_asio.reference.basic_socket.connect basic_socket::connect()] ]
+  ]
+  [
+    [`getaddrinfo()`,
+     `gethostbyaddr()`,
+     `gethostbyname()`,
+     `getnameinfo()`,
+     `getservbyname()`,
+     `getservbyport()`]
+    [ For TCP: [link boost_asio.reference.ip__basic_resolver.resolve ip::tcp::resolver::resolve()],
+               [link boost_asio.reference.ip__basic_resolver.async_resolve ip::tcp::resolver::async_resolve()]
+
+      For UDP: [link boost_asio.reference.ip__basic_resolver.resolve ip::udp::resolver::resolve()],
+               [link boost_asio.reference.ip__basic_resolver.async_resolve ip::udp::resolver::async_resolve()]
+
+               [link boost_asio.reference.ip__basic_resolver.resolve ip::basic_resolver::resolve()],
+               [link boost_asio.reference.ip__basic_resolver.async_resolve ip::basic_resolver::async_resolve()] ]
+  ]
+  [
+    [`gethostname()`]
+    [          [link boost_asio.reference.ip__host_name ip::host_name()] ]
+  ]
+  [
+    [`getpeername()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.remote_endpoint ip::tcp::socket::remote_endpoint()]
+
+      For UDP: [link boost_asio.reference.basic_socket.remote_endpoint ip::udp::socket::remote_endpoint()]
+
+               [link boost_asio.reference.basic_socket.remote_endpoint basic_socket::remote_endpoint()] ]
+  ]
+  [
+    [`getsockname()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.local_endpoint ip::tcp::acceptor::local_endpoint()],
+               [link boost_asio.reference.basic_socket.local_endpoint ip::tcp::socket::local_endpoint()]
+
+      For UDP: [link boost_asio.reference.basic_socket.local_endpoint ip::udp::socket::local_endpoint()]
+
+               [link boost_asio.reference.basic_socket.local_endpoint basic_socket::local_endpoint()] ]
+  ]
+  [
+    [`getsockopt()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.get_option ip::tcp::acceptor::get_option()],
+               [link boost_asio.reference.basic_socket.get_option ip::tcp::socket::get_option()]
+
+      For UDP: [link boost_asio.reference.basic_socket.get_option ip::udp::socket::get_option()]
+
+               [link boost_asio.reference.basic_socket.get_option basic_socket::get_option()] ]
+  ]
+  [
+    [`inet_addr()`,
+     `inet_aton()`,
+     `inet_pton()`]
+    [          [link boost_asio.reference.ip__address.from_string ip::address::from_string()],
+               [link boost_asio.reference.ip__address.from_string ip::address_v4::from_string()],
+               [link boost_asio.reference.ip__address.from_string ip_address_v6::from_string()] ]
+  ]
+  [
+    [`inet_ntoa()`,
+     `inet_ntop()`]
+    [          [link boost_asio.reference.ip__address.to_string ip::address::to_string()],
+               [link boost_asio.reference.ip__address.to_string ip::address_v4::to_string()],
+               [link boost_asio.reference.ip__address.to_string ip_address_v6::to_string()] ]
+  ]
+  [
+    [`ioctl()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.io_control ip::tcp::socket::io_control()]
+
+      For UDP: [link boost_asio.reference.basic_socket.io_control ip::udp::socket::io_control()]
+
+               [link boost_asio.reference.basic_socket.io_control basic_socket::io_control()] ]
+  ]
+  [
+    [`listen()`]
+    [ For TCP: [link boost_asio.reference.basic_socket_acceptor.listen ip::tcp::acceptor::listen()]
+
+               [link boost_asio.reference.basic_socket_acceptor.listen basic_socket_acceptor::listen()] ]
+  ]
+  [
+    [`poll()`,
+     `select()`,
+     `pselect()`]
+    [          [link boost_asio.reference.io_service.run io_service::run()],
+               [link boost_asio.reference.io_service.run_one io_service::run_one()],
+               [link boost_asio.reference.io_service.poll io_service::poll()],
+               [link boost_asio.reference.io_service.poll_one io_service::poll_one()]
+
+      Note: in conjunction with asynchronous operations. ]
+  ]
+  [
+    [`readv()`,
+     `recv()`,
+     `read()`]
+    [ For TCP: [link boost_asio.reference.basic_stream_socket.read_some ip::tcp::socket::read_some()],
+               [link boost_asio.reference.basic_stream_socket.async_read_some ip::tcp::socket::async_read_some()],
+               [link boost_asio.reference.basic_stream_socket.receive ip::tcp::socket::receive()],
+               [link boost_asio.reference.basic_stream_socket.async_receive ip::tcp::socket::async_receive()]
+
+      For UDP: [link boost_asio.reference.basic_datagram_socket.receive ip::udp::socket::receive()],
+               [link boost_asio.reference.basic_datagram_socket.async_receive ip::udp::socket::async_receive()]
+
+               [link boost_asio.reference.basic_stream_socket.read_some basic_stream_socket::read_some()],
+               [link boost_asio.reference.basic_stream_socket.async_read_some basic_stream_socket::async_read_some()],
+               [link boost_asio.reference.basic_stream_socket.receive basic_stream_socket::receive()],
+               [link boost_asio.reference.basic_stream_socket.async_receive basic_stream_socket::async_receive()],
+               [link boost_asio.reference.basic_datagram_socket.receive basic_datagram_socket::receive()],
+               [link boost_asio.reference.basic_datagram_socket.async_receive basic_datagram_socket::async_receive()] ]
+  ]
+  [
+    [`recvfrom()`]
+    [ For UDP: [link boost_asio.reference.basic_datagram_socket.receive_from ip::udp::socket::receive_from()],
+               [link boost_asio.reference.basic_datagram_socket.async_receive_from ip::udp::socket::async_receive_from()]
+
+               [link boost_asio.reference.basic_datagram_socket.receive_from basic_datagram_socket::receive_from()],
+               [link boost_asio.reference.basic_datagram_socket.async_receive_from basic_datagram_socket::async_receive_from()] ]
+  ]
+  [
+    [`send()`,
+     `write()`,
+     `writev()`]
+    [ For TCP: [link boost_asio.reference.basic_stream_socket.write_some ip::tcp::socket::write_some()],
+               [link boost_asio.reference.basic_stream_socket.async_write_some ip::tcp::socket::async_write_some()],
+               [link boost_asio.reference.basic_stream_socket.send ip::tcp::socket::send()],
+               [link boost_asio.reference.basic_stream_socket.async_send ip::tcp::socket::async_send()]
+
+      For UDP: [link boost_asio.reference.basic_datagram_socket.send ip::udp::socket::send()],
+               [link boost_asio.reference.basic_datagram_socket.async_send ip::udp::socket::async_send()]
+
+               [link boost_asio.reference.basic_stream_socket.write_some basic_stream_socket::write_some()],
+               [link boost_asio.reference.basic_stream_socket.async_write_some basic_stream_socket::async_write_some()],
+               [link boost_asio.reference.basic_stream_socket.send basic_stream_socket::send()],
+               [link boost_asio.reference.basic_stream_socket.async_send basic_stream_socket::async_send()],
+               [link boost_asio.reference.basic_datagram_socket.send basic_datagram_socket::send()],
+               [link boost_asio.reference.basic_datagram_socket.async_send basic_datagram_socket::async_send()] ]
+  ]
+  [
+    [`sendto()`]
+    [ For UDP: [link boost_asio.reference.basic_datagram_socket.send_to ip::udp::socket::send_to()],
+               [link boost_asio.reference.basic_datagram_socket.async_send_to ip::udp::socket::async_send_to()]
+
+               [link boost_asio.reference.basic_datagram_socket.send_to basic_datagram_socket::send_to()],
+               [link boost_asio.reference.basic_datagram_socket.async_send_to basic_datagram_socket::async_send_to()] ]
+  ]
+  [
+    [`setsockopt()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.set_option ip::tcp::acceptor::set_option()],
+               [link boost_asio.reference.basic_socket.set_option ip::tcp::socket::set_option()]
+
+      For UDP: [link boost_asio.reference.basic_socket.set_option ip::udp::socket::set_option()]
+
+               [link boost_asio.reference.basic_socket.set_option basic_socket::set_option()] ]
+  ]
+  [
+    [`shutdown()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.shutdown ip::tcp::socket::shutdown()]
+
+      For UDP: [link boost_asio.reference.basic_socket.shutdown ip::udp::socket::shutdown()]
+
+               [link boost_asio.reference.basic_socket.shutdown basic_socket::shutdown()] ]
+  ]
+  [
+    [`sockatmark()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.at_mark ip::tcp::socket::at_mark()]
+
+               [link boost_asio.reference.basic_socket.at_mark basic_socket::at_mark()] ]
+  ]
+  [
+    [`socket()`]
+    [ For TCP: [link boost_asio.reference.basic_socket.open ip::tcp::acceptor::open()],
+               [link boost_asio.reference.basic_socket.open ip::tcp::socket::open()]
+
+      For UDP: [link boost_asio.reference.basic_socket.open ip::udp::socket::open()]
+
+               [link boost_asio.reference.basic_socket.open basic_socket::open()] ]
+  ]
+  [
+    [`socketpair()`]
+    [          [link boost_asio.reference.local__connect_pair local::connect_pair()]
+
+      Note: POSIX operating systems only. ]
+  ]
+]
+
+[endsect]

Added: trunk/libs/asio/doc/overview/buffers.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/buffers.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,162 @@
+[/
+ / 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:buffers Buffers]
+
+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, Boost.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.
+
+Therefore we require an abstraction to represent a collection of buffers. The
+approach used in Boost.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.
+
+In addition to specifying buffers as a pointer and size in bytes, Boost.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;
+
+Here, a mutable_buffer would be convertible to a const_buffer, but conversion
+in the opposite direction is not valid.
+
+However, Boost.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:
+
+* Types behave as std::pair would in conversions. That is, a `mutable_buffer` is
+  convertible to a `const_buffer`, but the opposite conversion is disallowed.
+
+* There is protection against buffer overruns. Given a buffer instance, a user
+  can only create another buffer representing the same range of memory or a
+  sub-range of it. To provide further safety, the library also includes
+  mechanisms for automatically determining the size of a buffer from an array,
+  `boost::array` or `std::vector` of POD elements, or from a `std::string`.
+
+* Type safety violations must be explicitly requested using the `buffer_cast`
+  function. In general an application should never need to do this, but it is
+  required by the library implementation to pass the raw memory to the
+  underlying operating system functions.
+
+Finally, multiple buffers can be passed to scatter-gather operations (such as
+[link boost_asio.reference.read read()] or [link boost_asio.reference.write write()]) by
+putting the buffer objects 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 `boost::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
+  boost_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
+  boost_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 boost_asio.reference.basic_streambuf.commit
+  commit()] member function.
+
+* Data is removed from the front of the input sequence by calling the [link
+  boost_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:
+
+  boost::asio::streambuf sb;
+  ...
+  std::size_t n = boost::asio::read_until(sock, sb, '\n');
+  boost::asio::streambuf::const_buffers_type bufs = sb.data();
+  std::string line(
+      boost::asio::buffers_begin(bufs),
+      boost::asio::buffers_begin(bufs) + n);
+
+[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!
+
+Boost.Asio takes advantage of this feature to add buffer debugging. Consider the
+following code:
+
+  void dont_do_this()
+  {
+   std::string msg = "Hello, world!";
+   boost::asio::async_write(sock, boost::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, Boost.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 Boost.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 `BOOST_ASIO_ENABLE_BUFFER_DEBUGGING`.
+It can also be explicitly disabled by defining `BOOST_ASIO_DISABLE_BUFFER_DEBUGGING`.
+
+[heading See Also]
+
+[link boost_asio.reference.buffer buffer],
+[link boost_asio.reference.buffers_begin buffers_begin],
+[link boost_asio.reference.buffers_end buffers_end],
+[link boost_asio.reference.buffers_iterator buffers_iterator],
+[link boost_asio.reference.const_buffer const_buffer],
+[link boost_asio.reference.const_buffers_1 const_buffers_1],
+[link boost_asio.reference.mutable_buffer mutable_buffer],
+[link boost_asio.reference.mutable_buffers_1 mutable_buffers_1],
+[link boost_asio.reference.streambuf streambuf],
+[link boost_asio.reference.ConstBufferSequence ConstBufferSequence],
+[link boost_asio.reference.MutableBufferSequence MutableBufferSequence],
+[link boost_asio.examples.buffers buffers example].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/implementation.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/implementation.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,259 @@
+[/
+ / 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:implementation Platform-Specific Implementation Notes]
+
+This section lists platform-specific implementation details, such as the
+default demultiplexing mechanism, the number of threads created internally, and
+when threads are created.
+
+
+[heading Linux Kernel 2.4]
+
+Demultiplexing mechanism:
+
+* Uses `select` for demultiplexing. This means that the number of file
+descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
+
+Threads:
+
+* Demultiplexing using `select` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+[heading Linux Kernel 2.6]
+
+Demultiplexing mechanism:
+
+* Uses `epoll` for demultiplexing.
+
+Threads:
+
+* Demultiplexing using `epoll` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading Solaris]
+
+Demultiplexing mechanism:
+
+* Uses [^/dev/poll] for demultiplexing.
+
+Threads:
+
+* Demultiplexing using [^/dev/poll] is performed in one of the threads that
+calls `io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading QNX Neutrino]
+
+Demultiplexing mechanism:
+
+* Uses `select` for demultiplexing. This means that the number of file
+descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
+
+Threads:
+
+* Demultiplexing using `select` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading Mac OS X]
+
+Demultiplexing mechanism:
+
+* Uses `kqueue` for demultiplexing.
+
+Threads:
+
+* Demultiplexing using `kqueue` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading FreeBSD]
+
+Demultiplexing mechanism:
+
+* Uses `kqueue` for demultiplexing.
+
+Threads:
+
+* Demultiplexing using `kqueue` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading AIX]
+
+Demultiplexing mechanism:
+
+* Uses `select` for demultiplexing. This means that the number of file
+descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
+
+Threads:
+
+* Demultiplexing using `select` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading HP-UX]
+
+Demultiplexing mechanism:
+
+* Uses `select` for demultiplexing. This means that the number of file
+descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
+
+Threads:
+
+* Demultiplexing using `select` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading Tru64]
+
+Demultiplexing mechanism:
+
+* Uses `select` for demultiplexing. This means that the number of file
+descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
+
+Threads:
+
+* Demultiplexing using `select` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
+
+
+[heading Windows 95, 98 and Me]
+
+Demultiplexing mechanism:
+
+* Uses `select` for demultiplexing.
+
+Threads:
+
+* Demultiplexing using `select` is performed in one of the threads that calls
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* For sockets, at most 16 buffers may be transferred in a single operation.
+
+
+[heading Windows NT, 2000, XP, 2003 and Vista]
+
+Demultiplexing mechanism:
+
+* Uses overlapped I/O and I/O completion ports for all asynchronous socket
+operations except for asynchronous connect.
+
+* Uses `select` for emulating asynchronous connect.
+
+Threads:
+
+* Demultiplexing using I/O completion ports is performed in all threads that call
+`io_service::run()`, `io_service::run_one()`, `io_service::poll()` or
+`io_service::poll_one()`.
+
+* An additional thread per `io_service` is used for the `select`
+demultiplexing. This thread is created on the first call to `async_connect()`.
+
+* An additional thread per `io_service` is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
+
+Scatter-Gather:
+
+* For sockets, at most 64 buffers may be transferred in a single operation.
+
+* For stream-oriented handles, only one buffer may be transferred in a single
+operation.
+
+
+[endsect]

Added: trunk/libs/asio/doc/overview/iostreams.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/iostreams.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,46 @@
+[/
+ / 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:iostreams Socket Iostreams]
+
+Boost.Asio includes classes that implement iostreams on top of sockets. These hide
+away the complexities associated with endpoint resolution, protocol
+independence, etc. To create a connection one might simply write:
+
+  ip::tcp::iostream stream("www.boost.org", "http");
+  if (!stream)
+  {
+    // Can't connect.
+  }
+
+The iostream class can also be used in conjunction with an acceptor to create
+simple servers. For example:
+
+  io_service ios;
+
+  ip::tcp::endpoint endpoint(tcp::v4(), 80);
+  ip::tcp::acceptor acceptor(ios, endpoint);
+
+  for (;;)
+  {
+    ip::tcp::iostream stream;
+    acceptor.accept(*stream.rdbuf());
+    ...
+  }
+
+[heading See Also]
+
+[link boost_asio.reference.ip__tcp.iostream ip::tcp::iostream],
+[link boost_asio.reference.basic_socket_iostream basic_socket_iostream],
+[link boost_asio.examples.iostreams iostreams examples].
+
+[heading Notes]
+
+These iostream templates only support `char`, not `wchar_t`, and do not perform
+any code conversion.
+
+[endsect]

Added: trunk/libs/asio/doc/overview/line_based.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/line_based.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,118 @@
+[/
+ / 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:line_based Line-Based Operations]
+
+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, Boost.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:
+
+  class http_connection
+  {
+    ...
+
+    void start()
+    {
+      boost::asio::async_read_until(socket_, data_, "\r\n",
+          boost::bind(&http_connection::handle_request_line, this, _1));
+    }
+
+    void handle_request_line(boost::system::error_code ec)
+    {
+      if (!ec)
+      {
+        std::string method, uri, version;
+        char sp1, sp2, cr, lf;
+        std::istream is(&data_);
+        is.unsetf(std::ios_base::skipws);
+        is >> method >> sp1 >> uri >> sp2 >> version >> cr >> lf;
+        ...
+      }
+    }
+
+    ...
+
+    boost::asio::ip::tcp::socket socket_;
+    boost::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 boost::asio::buffers_iterator<
+      boost::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);
+  }
+  ...
+  boost::asio::streambuf b;
+  boost::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 boost { namespace asio {
+    template <> struct is_match_condition<match_char>
+      : public boost::true_type {};
+  } } // namespace boost::asio
+  ...
+  boost::asio::streambuf b;
+  boost::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 boost_asio.reference.async_read_until async_read_until()],
+[link boost_asio.reference.is_match_condition is_match_condition],
+[link boost_asio.reference.read_until read_until()],
+[link boost_asio.reference.streambuf streambuf],
+[link boost_asio.examples.http_client HTTP client example].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/posix.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/posix.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,105 @@
+[/
+ / 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:posix POSIX-Specific Functionality]
+
+[link boost_asio.overview.posix.local UNIX Domain Sockets]
+
+[link boost_asio.overview.posix.stream_descriptor Stream-Oriented File Descriptors]
+
+[section:local UNIX Domain Sockets]
+
+Boost.Asio provides basic support UNIX domain sockets (also known as local sockets).
+The simplest use involves creating a pair of connected sockets. The following
+code:
+
+  local::stream_protocol::socket socket1(my_io_service);
+  local::stream_protocol::socket socket2(my_io_service);
+  local::connect_pair(socket1, socket2);
+
+will create a pair of stream-oriented sockets. To do the same for
+datagram-oriented sockets, use:
+
+  local::datagram_protocol::socket socket1(my_io_service);
+  local::datagram_protocol::socket socket2(my_io_service);
+  local::connect_pair(socket1, socket2);
+
+A UNIX domain socket server may be created by binding an acceptor to an
+endpoint, in much the same way as one does for a TCP server:
+
+  ::unlink("/tmp/foobar"); // Remove previous binding.
+  local::stream_protocol::endpoint ep("/tmp/foobar");
+  local::stream_protocol::acceptor acceptor(my_io_service, ep);
+  local::stream_protocol::socket socket(my_io_service);
+  acceptor.accept(socket);
+
+A client that connects to this server might look like:
+
+  local::stream_protocol::endpoint ep("/tmp/foobar");
+  local::stream_protocol::socket socket(my_io_service);
+  socket.connect(ep);
+
+Transmission of file descriptors or credentials across UNIX domain sockets is
+not directly supported within Boost.Asio, but may be achieved by accessing the
+socket's underlying descriptor using the [link
+boost_asio.reference.basic_socket.native native()] member function.
+
+[heading See Also]
+
+[link boost_asio.reference.local__connect_pair local::connect_pair],
+[link boost_asio.reference.local__datagram_protocol local::datagram_protocol],
+[link boost_asio.reference.local__datagram_protocol.endpoint local::datagram_protocol::endpoint],
+[link boost_asio.reference.local__datagram_protocol.socket local::datagram_protocol::socket],
+[link boost_asio.reference.local__stream_protocol local::stream_protocol],
+[link boost_asio.reference.local__stream_protocol.acceptor local::stream_protocol::acceptor],
+[link boost_asio.reference.local__stream_protocol.endpoint local::stream_protocol::endpoint],
+[link boost_asio.reference.local__stream_protocol.iostream local::stream_protocol::iostream],
+[link boost_asio.reference.local__stream_protocol.socket local::stream_protocol::socket],
+[link boost_asio.examples.unix_domain_sockets UNIX domain sockets examples].
+
+[heading Notes]
+
+UNIX domain sockets are only available at compile time if supported by the
+target operating system. A program may test for the macro
+`BOOST_ASIO_HAS_LOCAL_SOCKETS` to determine whether they are supported.
+
+[endsect]
+
+[section:stream_descriptor Stream-Oriented File Descriptors]
+
+Boost.Asio includes classes added to permit synchronous and asynchronous read and
+write operations to be performed on POSIX file descriptors, such as pipes,
+standard input and output, and various devices (but /not/ regular files).
+
+For example, to perform read and write operations on standard input
+and output, the following objects may be created:
+
+  posix::stream_descriptor in(my_io_service, ::dup(STDIN_FILENO));
+  posix::stream_descriptor out(my_io_service, ::dup(STDOUT_FILENO));
+
+These are then used as synchronous or asynchronous read and write streams. This
+means the objects can be used with any of the [link boost_asio.reference.read
+read()], [link boost_asio.reference.async_read async_read()], [link
+boost_asio.reference.write write()], [link boost_asio.reference.async_write async_write()],
+[link boost_asio.reference.read_until read_until()] or [link
+boost_asio.reference.async_read_until async_read_until()] free functions.
+
+[heading See Also]
+
+[link boost_asio.reference.posix__stream_descriptor posix::stream_descriptor],
+[link boost_asio.reference.posix__basic_stream_descriptor posix::basic_stream_descriptor],
+[link boost_asio.reference.posix__stream_descriptor_service posix::stream_descriptor_service].
+
+[heading Notes]
+
+POSIX stream descriptors are only available at compile time if supported by the
+target operating system. A program may test for the macro
+`BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR` to determine whether they are supported.
+
+[endsect]
+
+[endsect]

Added: trunk/libs/asio/doc/overview/proactor.dot
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/proactor.dot	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,100 @@
+digraph g
+{
+  edge
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      labelfontname="Helvetica",
+      labelfontsize=10
+    ];
+
+  node
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      shape=record
+    ];
+
+  initiator
+    [
+      label="Initiator"
+    ];
+
+  async_processor
+    [
+      label="Asynchronous\nOperation Processor"
+    ];
+
+  async_op
+    [
+      label="Asynchronous\nOperation"
+    ];
+
+  completion_queue
+    [
+      label="Completion\nEvent Queue"
+    ];
+
+  async_event_demuxer
+    [
+      label="Asynchronous\nEvent Demultiplexer"
+    ];
+
+  proactor
+    [
+      label="Proactor"
+    ];
+
+  handler
+    [
+      label="Completion\nHandler"
+    ];
+
+  initiator -> async_processor
+    [
+      label="uses",
+      style="dashed"
+    ];
+
+  initiator -> async_op
+    [
+      label="starts",
+      style="dashed"
+    ];
+
+  initiator -> handler
+    [
+      label="creates",
+      style="dashed"
+    ];
+
+  async_processor -> async_op
+    [
+      label="executes",
+      style="dashed"
+    ];
+
+  async_processor -> completion_queue
+    [
+      label="enqueues",
+      style="dashed"
+    ];
+
+  async_op -> handler;
+
+  async_event_demuxer -> completion_queue
+    [
+      label="dequeues",
+      style="dashed"
+    ];
+
+  proactor -> async_event_demuxer
+    [
+    ];
+
+  proactor -> handler
+    [
+      label="demultiplexes\n& dispatches"
+      style="dashed"
+    ];
+}

Added: trunk/libs/asio/doc/overview/proactor.png
==============================================================================
Binary file. No diff available.

Added: trunk/libs/asio/doc/overview/rationale.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/rationale.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,54 @@
+[/
+ / 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:rationale Rationale]
+
+Most programs interact with the outside world in some way, whether it be via a
+file, a network, a serial cable, or the console. Sometimes, as is the case with
+networking, individual I/O operations can take a long time to complete. This
+poses particular challenges to application development.
+
+Boost.Asio provides the tools to manage these long running operations, without
+requiring programs to use concurrency models based on threads and explicit
+locking.
+
+The Boost.Asio library is intended for programmers using C++ for systems programming,
+where access to operating system functionality such as networking is often
+required. In particular, Boost.Asio addresses the following goals:
+
+* [*Portability.] The library should support a range of commonly used operating
+systems, and provide consistent behaviour across these operating systems.
+
+* [*Scalability.] The library should facilitate the development of network
+applications that scale to thousands of concurrent connections. The library
+implementation for each operating system should use the mechanism that best
+enables this scalability.
+
+* [*Efficiency.] The library should support techniques such as scatter-gather
+I/O, and allow programs to minimise data copying.
+
+* [*Model concepts from established APIs, such as BSD sockets.] The
+BSD socket API is widely implemented and understood, and is covered in much
+literature. Other programming languages often use a similar interface for
+networking APIs. As far as is reasonable, Boost.Asio should leverage existing
+practice.
+
+* [*Ease of use.] The library should provide a lower entry barrier for new
+users by taking a toolkit, rather than framework, approach. That is, it should
+try to minimise the up-front investment in time to just learning a few basic
+rules and guidelines. After that, a library user should only need to understand
+the specific functions that are being used.
+
+* [*Basis for further abstraction.] The library should permit the development
+of other libraries that provide higher levels of abstraction. For example,
+implementations of commonly used protocols such as HTTP.
+
+Although Boost.Asio started life focused primarily on networking, its concepts of
+asynchronous I/O have been extended to include other operating system resources
+such as serial ports, file descriptors, and so on.
+
+[endsect]

Added: trunk/libs/asio/doc/overview/reactor.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/reactor.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -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, Boost.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(boost::system::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 boost_asio.reference.null_buffers null_buffers],
+[link boost_asio.examples.nonblocking nonblocking example].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/serial_ports.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/serial_ports.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,47 @@
+[/
+ / 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:serial_ports Serial Ports]
+
+Boost.Asio includes classes for creating and manipulating serial ports in a portable
+manner. For example, a serial port may be opened using:
+
+  serial_port port(my_io_service, name);
+
+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 boost_asio.reference.read read()], [link
+boost_asio.reference.async_read async_read()], [link boost_asio.reference.write write()],
+[link boost_asio.reference.async_write async_write()], [link
+boost_asio.reference.read_until read_until()] or [link
+boost_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.
+
+[heading See Also]
+
+[link boost_asio.reference.serial_port serial_port],
+[link boost_asio.reference.serial_port_base serial_port_base],
+[link boost_asio.reference.basic_serial_port basic_serial_port],
+[link boost_asio.reference.serial_port_service serial_port_service],
+[link boost_asio.reference.serial_port_base__baud_rate serial_port_base::baud_rate],
+[link boost_asio.reference.serial_port_base__flow_control serial_port_base::flow_control],
+[link boost_asio.reference.serial_port_base__parity serial_port_base::parity],
+[link boost_asio.reference.serial_port_base__stop_bits serial_port_base::stop_bits],
+[link boost_asio.reference.serial_port_base__character_size serial_port_base::character_size].
+
+[heading Notes]
+
+Serial ports are available on all POSIX platforms. For Windows, serial ports
+are only available at compile time when the I/O completion port backend is used
+(which is the default). A program may test for the macro
+`BOOST_ASIO_HAS_SERIAL_PORTS` to determine whether they are supported.
+
+[endsect]

Added: trunk/libs/asio/doc/overview/ssl.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/ssl.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,68 @@
+[/
+ / 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:ssl SSL]
+
+Boost.Asio contains classes and class templates for basic SSL support. These classes
+allow encrypted communication to be layered on top of an existing stream, such
+as a TCP socket.
+
+Before creating an encrypted stream, an application must construct an SSL
+context object. This object is used to set SSL options such as verification
+mode, certificate files, and so on. As an illustration, client-side
+initialisation may look something like:
+
+  ssl::context ctx(io_service, ssl::context::sslv23);
+  ctx.set_verify_mode(ssl::context::verify_peer);
+  ctx.load_verify_file("ca.pem");
+
+To use SSL with a TCP socket, one may write:
+
+  ssl::stream<ip::tcp::socket> ssl_sock(my_io_service, ctx);
+
+To perform socket-specific operations, such as establishing an outbound
+connection or accepting an incoming one, the underlying socket must first be
+obtained using the `ssl::stream` template's [link
+boost_asio.reference.ssl__stream.lowest_layer `lowest_layer()`] member function:
+
+  ip::tcp::socket& sock = ssl_sock.lowest_layer();
+  sock.connect(my_endpoint);
+
+In some use cases the underlying stream object will need to have a longer
+lifetime than the SSL stream, in which case the template parameter should be a
+reference to the stream type:
+
+  ip::tcp::socket sock(my_io_service);
+  ssl::stream<ip::tcp::socket&> ssl_sock(sock, ctx);
+
+Once connected, SSL stream objects are used as synchronous or asynchronous read
+and write streams. This means the objects can be used with any of the [link
+boost_asio.reference.read read()], [link boost_asio.reference.async_read async_read()],
+[link boost_asio.reference.write write()], [link boost_asio.reference.async_write
+async_write()], [link boost_asio.reference.read_until read_until()] or [link
+boost_asio.reference.async_read_until async_read_until()] free functions.
+
+[heading See Also]
+
+[link boost_asio.reference.ssl__basic_context ssl::basic_context],
+[link boost_asio.reference.ssl__context ssl::context],
+[link boost_asio.reference.ssl__context_base ssl::context_base],
+[link boost_asio.reference.ssl__context_service ssl::context_service],
+[link boost_asio.reference.ssl__stream ssl::stream],
+[link boost_asio.reference.ssl__stream_base ssl::stream_base],
+[link boost_asio.reference.ssl__stream_service ssl::stream_service],
+[link boost_asio.examples.ssl SSL example].
+
+[heading Notes]
+
+[@http://www.openssl.org OpenSSL] is required to make use of Boost.Asio's SSL
+support. When an application needs to use OpenSSL functionality that is not
+wrapped by Boost.Asio, the underlying OpenSSL types may be obtained by calling [link
+boost_asio.reference.ssl__basic_context.impl `ssl::context::impl()`] or [link
+boost_asio.reference.ssl__stream.impl `ssl::stream::impl()`].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/strands.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/strands.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,62 @@
+[/
+ / 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:strands Strands: Use Threads Without Explicit Locking]
+
+A strand is defined as a strictly sequential invocation of event handlers (i.e.
+no concurrent invocation). Use of strands allows execution of code in a
+multithreaded program without the need for explicit locking (e.g. using
+mutexes).
+
+Strands may be either implicit or explicit, as illustrated by the following
+alternative approaches:
+
+* Calling io_service::run() from only one thread means all event handlers
+  execute in an implicit strand, due to the io_service's guarantee that handlers
+  are only invoked from inside run().
+
+* Where there is a single chain of asynchronous operations associated with a
+  connection (e.g. in a half duplex protocol implementation like HTTP) there is
+  no possibility of concurrent execution of the handlers. This is an implicit
+  strand.
+
+* An explicit strand is an instance of `io_service::strand`. All event handler
+  function objects need to be wrapped using `io_service::strand::wrap()` or
+  otherwise posted/dispatched through the `io_service::strand` object.
+
+In the case of composed asynchronous operations, such as `async_read()` or
+`async_read_until()`, if a completion handler goes through a strand, then all
+intermediate handlers should also go through the same strand. This is needed to
+ensure thread safe access for any objects that are shared between the caller
+and the composed operation (in the case of `async_read()` it's the socket,
+which the caller can close() to cancel the operation). This is done by having
+hook functions for all intermediate handlers which forward the calls to the
+customisable hook associated with the final handler:
+
+  struct my_handler
+  {
+    void operator()() { ... }
+  };
+
+  template<class F>
+  void asio_handler_invoke(F f, my_handler*)
+  {
+    // Do custom invocation here.
+    // Default implementation calls f();
+  }
+
+The `io_service::strand::wrap()` function creates a new completion handler that
+defines `asio_handler_invoke` so that the function object is executed through
+the strand.
+
+[heading See Also]
+
+[link boost_asio.reference.io_service__strand io_service::strand],
+[link boost_asio.tutorial.tuttimer5 tutorial Timer.5],
+[link boost_asio.examples.http_server_3 HTTP server 3 example].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/streams.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/streams.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,62 @@
+[/
+ / 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:streams Streams, Short Reads and Short Writes]
+
+Many I/O objects in Boost.Asio are stream-oriented. This means that:
+
+* There are no message boundaries. The data being transferred is a continuous
+  sequence of bytes.
+
+* Read or write operations may transfer fewer bytes than requested. This is
+  referred to as a short read or short write.
+
+Objects that provide stream-oriented I/O model one or more of the following
+type requirements:
+
+* `SyncReadStream`, where synchronous read operations are performed using a
+  member function called `read_some()`.
+
+* `AsyncReadStream`, where asynchronous read operations are performed using a
+  member function called `async_read_some()`.
+
+* `SyncWriteStream`, where synchronous write operations are performed using a
+  member function called `write_some()`.
+
+* `AsyncWriteStream`, where synchronous write operations are performed using a
+  member function called `async_write_some()`.
+
+Examples of stream-oriented I/O objects include `ip::tcp::socket`,
+`ssl::stream<>`, `posix::stream_descriptor`, `windows::stream_handle`, etc.
+
+Programs typically want to transfer an exact number of bytes. When a short read
+or short write occurs the program must restart the operation, and continue to
+do so until the required number of bytes has been transferred. Boost.Asio provides
+generic functions that do this automatically: `read()`, `async_read()`,
+`write()` and `async_write()`.
+
+[heading Why EOF is an Error]
+
+* The end of a stream can cause `read`, `async_read`, `read_until` or
+  `async_read_until` functions to violate their contract. E.g.
+  a read of N bytes may finish early due to EOF.
+
+* An EOF error may be used to distinguish the end of a stream from a successful
+  read of size 0.
+
+[heading See Also]
+
+[link boost_asio.reference.async_read async_read()],
+[link boost_asio.reference.async_write async_write()],
+[link boost_asio.reference.read read()],
+[link boost_asio.reference.write write()],
+[link boost_asio.reference.AsyncReadStream AsyncReadStream],
+[link boost_asio.reference.AsyncWriteStream AsyncWriteStream],
+[link boost_asio.reference.SyncReadStream SyncReadStream],
+[link boost_asio.reference.SyncWriteStream SyncWriteStream].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/threads.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/threads.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,76 @@
+[/
+ / 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:threads Threads and Boost.Asio]
+
+[heading Thread Safety]
+
+In general, it is safe to make concurrent use of distinct objects, but unsafe
+to make concurrent use of a single object. However, types such as `io_service`
+provide a stronger guarantee that it is safe to use a single object
+concurrently.
+
+[heading Thread Pools]
+
+Multiple threads may call `io_service::run()` to set up a pool of threads from
+which completion handlers may be invoked. This approach may also be used with
+`io_service::post()` to use a means to perform any computational tasks across a
+thread pool.
+
+Note that all threads that have joined an `io_service`'s pool are considered
+equivalent, and the `io_service` may distribute work across them in an
+arbitrary fashion.
+
+[heading Internal Threads]
+
+The implementation of this library for a particular platform may make use of
+one or more internal threads to emulate asynchronicity. As far as possible,
+these threads must be invisible to the library user. In particular, the threads:
+
+* must not call the user's code directly; and
+
+* must block all signals.
+
+[note The implementation currently violates the first of these rules for the
+following functions:
+
+[mdash] `ip::basic_resolver::async_resolve()` on all platforms.
+
+[mdash] `basic_socket::async_connect()` on Windows.
+
+[mdash] Any operation involving `null_buffers()` on Windows, other than an
+asynchronous read performed on a stream-oriented socket.]
+
+This approach is complemented by the following guarantee:
+
+* Asynchronous completion handlers will only be called from threads that are
+  currently calling `io_service::run()`.
+
+Consequently, it is the library user's responsibility to create and manage all
+threads to which the notifications will be delivered.
+
+The reasons for this approach include:
+
+* By only calling `io_service::run()` from a single thread, the user's code can
+  avoid the development complexity associated with synchronisation. For
+  example, a library user can implement scalable servers that are
+  single-threaded (from the user's point of view).
+
+* A library user may need to perform initialisation in a thread shortly after
+  the thread starts and before any other application code is executed. For
+  example, users of Microsoft's COM must call `CoInitializeEx` before any other
+  COM operations can be called from that thread.
+
+* The library interface is decoupled from interfaces for thread creation and
+  management, and permits implementations on platforms where threads are not
+  available.
+
+[heading See Also]
+
+[link boost_asio.reference.io_service io_service].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/timers.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/timers.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -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
+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(boost::system::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 boost_asio.reference.basic_deadline_timer basic_deadline_timer],
+[link boost_asio.reference.deadline_timer deadline_timer],
+[link boost_asio.reference.deadline_timer_service deadline_timer_service],
+[link boost_asio.tutorial.tuttimer1 timer tutorials].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/windows.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/windows.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -0,0 +1,91 @@
+[/
+ / 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:windows Windows-Specific Functionality]
+
+[link boost_asio.overview.windows.stream_handle Stream-Oriented HANDLEs]
+
+[link boost_asio.overview.windows.random_access_handle Random-Access HANDLEs]
+
+[section:stream_handle Stream-Oriented HANDLEs]
+
+Boost.Asio contains classes to allow asynchronous read and write operations to be
+performed on Windows `HANDLE`s, such as named pipes.
+
+For example, to perform asynchronous operations on a named pipe, the following
+object may be created:
+
+  HANDLE handle = ::CreateFile(...);
+  windows::stream_handle pipe(my_io_service, handle);
+
+These are then used as synchronous or asynchronous read and write streams. This
+means the objects can be used with any of the [link boost_asio.reference.read
+read()], [link boost_asio.reference.async_read async_read()], [link
+boost_asio.reference.write write()], [link boost_asio.reference.async_write
+async_write()], [link boost_asio.reference.read_until read_until()] or [link
+boost_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
+pipes and console streams are not).
+
+[heading See Also]
+
+[link boost_asio.reference.windows__stream_handle windows::stream_handle],
+[link boost_asio.reference.windows__basic_stream_handle windows::basic_stream_handle],
+[link boost_asio.reference.windows__stream_handle_service windows::stream_handle_service].
+
+[heading Notes]
+
+Windows stream `HANDLE`s are only available at compile time when targeting
+Windows and only when the I/O completion port backend is used (which is the
+default). A program may test for the macro `BOOST_ASIO_HAS_WINDOWS_STREAM_HANDLE` to
+determine whether they are supported.
+
+[endsect]
+
+[/-----------------------------------------------------------------------------]
+
+[section:random_access_handle Random-Access HANDLEs]
+
+Boost.Asio provides Windows-specific classes that permit asynchronous read and write
+operations to be performed on HANDLEs that refer to regular files.
+
+For example, to perform asynchronous operations on a file the following object
+may be created:
+
+  HANDLE handle = ::CreateFile(...);
+  windows::random_access_handle file(my_io_service, handle);
+
+Data may be read from or written to the handle using one of the
+`read_some_at()`, `async_read_some_at()`, `write_some_at()` or
+`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 boost_asio.reference.read_at read_at()], [link
+boost_asio.reference.async_read_at async_read_at()], [link boost_asio.reference.write_at
+write_at()] and [link boost_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]
+
+[link boost_asio.reference.windows__random_access_handle windows::random_access_handle],
+[link boost_asio.reference.windows__basic_random_access_handle windows::basic_random_access_handle],
+[link boost_asio.reference.windows__random_access_handle_service windows::random_access_handle_service].
+
+[heading Notes]
+
+Windows random-access `HANDLE`s are only available at compile time when
+targeting Windows and only when the I/O completion port backend is used (which
+is the default). A program may test for the macro
+`BOOST_ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE` to determine whether they are
+supported.
+
+[endsect]
+
+[endsect]

Modified: trunk/libs/asio/doc/using.qbk
==============================================================================
--- trunk/libs/asio/doc/using.qbk	(original)
+++ trunk/libs/asio/doc/using.qbk	2008-07-17 11:05:24 EDT (Thu, 17 Jul 2008)
@@ -264,4 +264,11 @@
   ]
 ]
 
+[heading Mailing List]
+
+A mailing list specifically for Boost.Asio may be found on
+[@http://sourceforge.net/mail/?group_id=122478 SourceForge.net]. Newsgroup
+access is provided via [@http://dir.gmane.org/gmane.comp.lib.boost.asio.user
+Gmane].
+
 [endsect]