Document platform-specific implementation.

asio/src/doc/Makefile.am

@@ -121,6 +121,7 @@ EXTRA_DIST = \
 	design/buffers_dox.txt \
 	design/closeascancel_dox.txt \
 	design/handlers_dox.txt \
+	design/implementation_dox.txt \
 	design/index_dox.txt \
 	design/proactor_dox.txt \
 	design/services_dox.txt \

asio/src/doc/boost/design.dox

@@ -78,7 +78,8 @@ INPUT                  = ./design_dox.txt \
                          ./design/services_dox.txt \
                          ./design/threads_dox.txt \
                          ./design/buffers_dox.txt \
-                         ./design/proactor_dox.txt
+                         ./design/proactor_dox.txt \
+                         ./design/implementation_dox.txt
 FILE_PATTERNS          = 
 RECURSIVE              = NO
 EXCLUDE                = 

asio/src/doc/boost/design_dox.txt

@@ -3,11 +3,32 @@
 
 Some design notes:
 
-\li \ref designservices
-\li \ref designhandlers
-\li \ref designcloseascancel
-\li \ref designthreads
-\li \ref designbuffers
-\li \ref designproactor
+\li <b>\ref designproactor</b>: The Boost.Asio library is based on the Proactor
+pattern. This design note outlines the advantages and disadvantages of this
+approach.
+
+\li <b>\ref designthreads</b>: 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.
+
+\li <b>\ref designservices</b>: This design note describes the pattern used for
+structuring asynchronous object implementation.
+
+\li <b>\ref designhandlers</b>: All asynchronous operations take a function
+object that will be called when the operation completes. This design note
+outlines the reasons for making the this handler type a template parameter,
+rather than using boost::function.
+
+\li <b>\ref designcloseascancel</b>: Asynchronous socket operations can be
+cancelled by closing the socket. This design note describes why this approach
+was selected rather than allowing individual operations to be cancelled.
+
+\li <b>\ref designbuffers</b>: This design note examines the buffer abstraction
+used by Boost.Asio in order to support scatter-gather operations.
+
+\li <b>\ref designimplementation</b>: 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.
 
 */

asio/src/doc/design.dox.in

@@ -378,7 +378,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ./design/index_dox.txt ./design/handlers_dox.txt ./design/closeascancel_dox.txt ./design/services_dox.txt ./design/threads_dox.txt ./design/buffers_dox.txt ./design/proactor_dox.txt
+INPUT                  = ./design/index_dox.txt ./design/handlers_dox.txt ./design/closeascancel_dox.txt ./design/services_dox.txt ./design/threads_dox.txt ./design/buffers_dox.txt ./design/proactor_dox.txt ./design/implementation_dox.txt
 
 # If the value of the INPUT tag contains directories, you can use the 
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 

asio/src/doc/design/implementation_dox.txt

@@ -0,0 +1,121 @@
+/**
+\page designimplementation 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.
+
+
+\section linux24 Linux Kernel 2.4
+
+\subsection linux24demux Demultiplexing Mechanism
+
+Uses \c select for demultiplexing. This means that the number of file
+descriptors in the process cannot be permitted to exceed FD_SETSIZE.
+
+\subsection linux24threads Threads
+
+Demultiplexing using \c select is performed in one of the threads that calls
+asio::demuxer::run().
+
+An additional thread per demuxer is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+asio::ipv4::host_resolver::async_get_host_by_address() or
+asio::ipv4::host_resolver::async_get_host_by_name().
+
+
+\section linux26 Linux Kernel 2.6
+
+\subsection linux26demux Demultiplexing Mechanism
+
+Uses \c epoll for demultiplexing.
+
+\subsection linux26threads Threads
+
+Demultiplexing using \c epoll is performed in one of the threads that calls
+asio::demuxer::run().
+
+An additional thread per demuxer is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+asio::ipv4::host_resolver::async_get_host_by_address() or
+asio::ipv4::host_resolver::async_get_host_by_name().
+
+
+\section solaris Solaris
+
+\subsection solarisdemux Demultiplexing Mechanism
+
+Uses \c select for demultiplexing. This means that the number of file
+descriptors in the process cannot be permitted to exceed FD_SETSIZE.
+
+\subsection solaristhreads Threads
+
+Demultiplexing using \c select is performed in one of the threads that calls
+asio::demuxer::run().
+
+An additional thread per demuxer is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+asio::ipv4::host_resolver::async_get_host_by_address() or
+asio::ipv4::host_resolver::async_get_host_by_name().
+
+
+\section macosx Mac OS X
+
+\subsection macosxdemux Demultiplexing Mechanism
+
+Uses \c kqueue for demultiplexing.
+
+\subsection macosxthreads Threads
+
+Demultiplexing using \c kqueue is performed in one of the threads that calls
+asio::demuxer::run().
+
+An additional thread per demuxer is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+asio::ipv4::host_resolver::async_get_host_by_address() or
+asio::ipv4::host_resolver::async_get_host_by_name().
+
+
+\section win9x Windows 95, 98 and Me
+
+\subsection win9xdemux Demultiplexing Mechanism
+
+Uses \c select for demultiplexing.
+
+\subsection win9xthreads Threads
+
+Demultiplexing using \c select is performed in one of the threads that calls
+asio::demuxer::run().
+
+An additional thread per demuxer is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+asio::ipv4::host_resolver::async_get_host_by_address() or
+asio::ipv4::host_resolver::async_get_host_by_name().
+
+
+\section winnt Windows NT, 2000 and XP
+
+\subsection winntdemux Demultiplexing Mechanism
+
+Uses overlapped I/O and I/O completion ports for all asynchronous
+datagram_socket, stream_socket and socket_acceptor operations except for
+asynchronous connect.
+
+Uses \c select for deadline_timer operations and for emulating asynchronous
+connect.
+
+\subsection winnthreads Threads
+
+Demultiplexing using I/O completion ports is performed in all threads that call
+asio::demuxer::run().
+
+An additional thread per demuxer is used to for the \c select demultiplexing.
+This thread is created whenever the first deadline_timer, datagram_socket,
+stream_socket or socket_acceptor is created.
+
+An additional thread per demuxer is used to emulate asynchronous host
+resolution. This thread is created on the first call to either
+asio::ipv4::host_resolver::async_get_host_by_address() or
+asio::ipv4::host_resolver::async_get_host_by_name().
+
+*/

asio/src/doc/design/index_dox.txt

@@ -3,11 +3,32 @@
 
 Some design notes:
 
-\li \ref designservices
-\li \ref designhandlers
-\li \ref designcloseascancel
-\li \ref designthreads
-\li \ref designbuffers
-\li \ref designproactor
+\li <b>\ref designproactor</b>: The asio library is based on the Proactor
+pattern. This design note outlines the advantages and disadvantages of this
+approach.
+
+\li <b>\ref designthreads</b>: An implementation of 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.
+
+\li <b>\ref designservices</b>: This design note describes the pattern used for
+structuring asynchronous object implementation.
+
+\li <b>\ref designhandlers</b>: All asynchronous operations take a function
+object that will be called when the operation completes. This design note
+outlines the reasons for making the this handler type a template parameter,
+rather than using boost::function.
+
+\li <b>\ref designcloseascancel</b>: Asynchronous socket operations can be
+cancelled by closing the socket. This design note describes why this approach
+was selected rather than allowing individual operations to be cancelled.
+
+\li <b>\ref designbuffers</b>: This design note examines the buffer abstraction
+used by asio in order to support scatter-gather operations.
+
+\li <b>\ref designimplementation</b>: 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.
 
 */