From 1e87571a5e9aae0bdfbeb5ae619ec606c3e6515f Mon Sep 17 00:00:00 2001 From: chris_kohlhoff Date: Wed, 7 Dec 2005 12:54:53 +0000 Subject: [PATCH] Document platform-specific implementation. --- asio/src/doc/Makefile.am | 1 + asio/src/doc/boost/design.dox | 3 +- asio/src/doc/boost/design_dox.txt | 33 +++++- asio/src/doc/design.dox.in | 2 +- asio/src/doc/design/implementation_dox.txt | 121 +++++++++++++++++++++ asio/src/doc/design/index_dox.txt | 33 +++++- 6 files changed, 179 insertions(+), 14 deletions(-) create mode 100644 asio/src/doc/design/implementation_dox.txt diff --git a/asio/src/doc/Makefile.am b/asio/src/doc/Makefile.am index 1f92a9d2..3709d594 100644 --- a/asio/src/doc/Makefile.am +++ b/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 \ diff --git a/asio/src/doc/boost/design.dox b/asio/src/doc/boost/design.dox index dfab04f1..da1abd81 100644 --- a/asio/src/doc/boost/design.dox +++ b/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 = diff --git a/asio/src/doc/boost/design_dox.txt b/asio/src/doc/boost/design_dox.txt index 49ebae6c..dfecd946 100644 --- a/asio/src/doc/boost/design_dox.txt +++ b/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 \ref designproactor: The Boost.Asio library is based on the Proactor +pattern. This design note outlines the advantages and disadvantages of this +approach. + +\li \ref designthreads: 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 \ref designservices: This design note describes the pattern used for +structuring asynchronous object implementation. + +\li \ref designhandlers: 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 \ref designcloseascancel: 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 \ref designbuffers: This design note examines the buffer abstraction +used by Boost.Asio in order to support scatter-gather operations. + +\li \ref designimplementation: 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. */ diff --git a/asio/src/doc/design.dox.in b/asio/src/doc/design.dox.in index 2083ef20..bf369a04 100644 --- a/asio/src/doc/design.dox.in +++ b/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 diff --git a/asio/src/doc/design/implementation_dox.txt b/asio/src/doc/design/implementation_dox.txt new file mode 100644 index 00000000..ae6b2cae --- /dev/null +++ b/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(). + +*/ diff --git a/asio/src/doc/design/index_dox.txt b/asio/src/doc/design/index_dox.txt index ba570016..1ba94014 100644 --- a/asio/src/doc/design/index_dox.txt +++ b/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 \ref designproactor: The asio library is based on the Proactor +pattern. This design note outlines the advantages and disadvantages of this +approach. + +\li \ref designthreads: 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 \ref designservices: This design note describes the pattern used for +structuring asynchronous object implementation. + +\li \ref designhandlers: 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 \ref designcloseascancel: 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 \ref designbuffers: This design note examines the buffer abstraction +used by asio in order to support scatter-gather operations. + +\li \ref designimplementation: 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. */