Update of /cvsroot/boost/boost/libs/asio/doc
In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv24810
Modified Files:
Jamfile.v2 asio.qbk design.qbk quickref.xml reference.qbk
reference.xsl tutorial.qbk
Added Files:
using.qbk
Removed Files:
requirements.qbk
Log Message:
Documentation updates.
--- NEW FILE: using.qbk ---
[/
/ Copyright (c) 2003-2007 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:using Using Boost.Asio]
[heading Supported Platforms]
The following platforms and compilers have been tested:
* Win32 and Win64 using Visual C++ 7.1 and Visual C++ 8.0.
* Win32 using Borland C++Builder 6 patch 4.
* Win32 using MinGW.
* Win32 using Cygwin. (`__USE_W32_SOCKETS` must be defined.)
* Linux (2.4 or 2.6 kernels) using g++ 3.3 or later.
* Solaris using g++ 3.3 or later.
* Mac OS X 10.4 using g++ 3.3 or later.
* QNX Neutrino 6.3 using g++ 3.3 or later.
[heading Dependencies]
The following libraries must be available in order to link programs that use
Boost.Asio:
* Boost.System for the `boost::system::error_code` and
`boost::system::system_error` classes.
* Boost.Regex (optional) if you use any of the [link
boost_asio.reference.read_until `read_until()`] or [link
boost_asio.reference.async_read_until `async_read_until()`] overloads that take
a `boost::regex` parameter.
* [EMAIL PROTECTED]://www.openssl.org OpenSSL] (optional) if you use
Boost.Asio's SSL
support.
Furthermore, some of the examples also require the Boost.Thread,
Boost.Date_Time or Boost.Serialization libraries.
[note With MSVC or Borland C++ you may want to add `-DBOOST_DATE_TIME_NO_LIB`
and `-DBOOST_REGEX_NO_LIB` to your project settings to disable autolinking of
the Boost.Date_Time and Boost.Regex libraries respectively. Alternatively, you
may choose to build these libraries and link to them.]
[heading Building Boost Libraries]
You may build the subset of Boost libraries required to use Boost.Asio and its
examples by running the following command from the root of the Boost download
package:
[pre
bjam --with-system --with-thread --with-date_time --with-regex
--with-serialization stage
]
This assumes that you have already built `bjam`. Consult the Boost.Build
documentation for more details.
[/
[heading Compiling Programs With Boost.Asio]
Consider the following minimal Boost.Asio program [^simple.cpp]:
#include <boost/asio.hpp>
#include <iostream>
#include <ostream>
int main()
{
boost::asio::ip::tcp::iostream s("www.boost.org", "http");
s << "GET / HTTP/1.0\r\n";
s << "Host: www.boost.org\r\n";
s << "\r\n" << std::flush;
std::cout << s.rdbuf();
return 0;
}
The following compiler commands may be used to build the program (note that the
name of the `boost_system` library may vary depending on the compiler version):
[table
[
[OS]
[Compiler]
[Command]
]
[
[FreeBSD]
[g++]
[[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib
-lboost_system-gcc]]
]
[
[Linux]
[g++]
[[^g++ -I['boost_root] -pthread simple.cpp -L['boost_root]/stage/lib
-lboost_system-gcc41]]
]
[
[Mac OS X]
[g++]
[[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system]]
]
[
[Solaris]
[g++]
[[^g++ -I['boost_root] simple.cpp -L['boost_root]/stage/lib -lboost_system
-lsocket -lnsl -lpthread]]
]
[
[Windows]
[MSVC 7.1]
[[^cl /EHsc /GR /MT -I['boost_root] /D_WIN32_WINNT=0x500 simple.cpp /link
/libpath:['boost_root]/stage/lib]]
]
[
[Windows]
[MSVC 8.0]
[[^cl /EHsc /GR /MT /I['boost_root] /D_WIN32_WINNT=0x500 simple.cpp /link
/libpath:['boost_root]/stage/lib]]
]
]
]
[endsect]
Index: Jamfile.v2
===================================================================
RCS file: /cvsroot/boost/boost/libs/asio/doc/Jamfile.v2,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- Jamfile.v2 19 Jan 2007 01:57:08 -0000 1.3
+++ Jamfile.v2 16 May 2007 14:35:08 -0000 1.4
@@ -25,7 +25,7 @@
<xsl:param>toc.section.depth=2
<xsl:param>toc.max.depth=1
<xsl:param>generate.section.toc.level=1
- <xsl:param>generate.toc="\"chapter toc,title section toc,title\""
+ <xsl:param>generate.toc="\"chapter nop section nop\""
;
Index: asio.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/asio/doc/asio.qbk,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- asio.qbk 22 Apr 2007 09:34:13 -0000 1.4
+++ asio.qbk 16 May 2007 14:35:08 -0000 1.5
@@ -40,89 +40,55 @@
provides developers with a consistent asynchronous I/O model using a modern C++
approach.
-[heading Quick Reference]
-
-[xinclude quickref.xml]
-
-[heading Getting Started]
-
-The [link boost_asio.tutorial tutorial] introduces the fundamental concepts
-required to use Boost.Asio, and shows how to use Boost.Asio to develop simple
-client and server programs.
-
-The [link boost_asio.examples examples] illustrate the use of Boost.Asio in
-more complex applications.
-
-[heading Dependencies]
-
-The following libraries must be available in order to link programs that use
-Boost.Asio:
-
-* Boost.System
-
-* Boost.Regex (optional) if you use any of the [link
-boost_asio.reference.read_until `read_until()`] or [link
-boost_asio.reference.async_read_until `async_read_until()`] overloads that take
-a `boost::regex` parameter.
-
-* [EMAIL PROTECTED]://www.openssl.org OpenSSL] (optional) if you use
Boost.Asio's SSL
-support.
-
-Note: with MSVC or Borland C++ you may want to add `-DBOOST_DATE_TIME_NO_LIB`
-and `-DBOOST_REGEX_NO_LIB` to your project settings to disable autolinking of
-the Boost.Date_Time and Boost.Regex libraries respectively.
-
-[heading Supported Platforms]
-
-The following platforms and compilers have been tested:
-
-* Win32 and Win64 using Visual C++ 7.1 and Visual C++ 8.0.
-* Win32 using Borland C++Builder 6 patch 4.
-* Win32 using MinGW.
-* Win32 using Cygwin. (`__USE_W32_SOCKETS` must be defined.)
-* Linux (2.4 or 2.6 kernels) using g++ 3.3 or later.
-* Solaris using g++ 3.3 or later.
-* Mac OS X 10.4 using g++ 3.3 or later.
-* QNX Neutrino 6.3 using g++ 3.3 or later.
-
-[heading Rationale]
-
-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 attempts to address the following
-goals:
-
-* [*Portability.] The library should support, and provide consistent behaviour
-across, a range of commonly used operating systems.
-
-* [*Scalability.] The library should allow, and indeed encourage, the
-development of network applications that scale to hundreds or 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 protocol implementations that minimise data copying.
-
-* [*Model Berkeley sockets.] The Berkeley sockets API is widely implemented and
-understood, as well as being covered in much literature. Other programming
-languages often use a similar interface for networking APIs.
-
-* [*Ease of use.] Lower the entry barrier for new users by taking a toolkit,
-rather than framework, approach. That is, 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 the current incarnation of Boost.Asio focuses primarily on networking,
-its concepts of asynchronous I/O can be extended to include other operating
-system resources such as files.
+[variablelist
+ [
+ [
+ [link boost_asio.using Using Boost.Asio]
+ ]
+ [
+ How to use Boost.Asio in your applications. Includes information on
+ library dependencies and supported platforms.
+ ]
+ ]
+ [
+ [
+ [link boost_asio.tutorial Tutorial]
+ ]
+ [
+ A tutorial that introduces the fundamental concepts required to use
+ Boost.Asio, and shows how to use Boost.Asio to develop simple client and
+ server programs.
+ ]
+ ]
+ [
+ [
+ [link boost_asio.examples Examples]
+ ]
+ [
+ Examples that illustrate the use of Boost.Asio in more complex
+ applications.
+ ]
+ ]
+ [
+ [
+ [link boost_asio.reference Reference]
+ ]
+ [
+ Detailed class and function reference.
+ ]
+ ]
+ [
+ [
+ [link boost_asio.design Design]
+ ]
+ [
+ Rationale and design information for Boost.Asio.
+ ]
+ ]
+]
+[include using.qbk]
[include tutorial.qbk]
[include examples.qbk]
-[include requirements.qbk]
[include reference.qbk]
[include design.qbk]
Index: design.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/asio/doc/design.qbk,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- design.qbk 19 Jan 2007 01:20:15 -0000 1.1
+++ design.qbk 16 May 2007 14:35:08 -0000 1.2
@@ -7,6 +7,91 @@
[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]
Index: quickref.xml
===================================================================
RCS file: /cvsroot/boost/boost/libs/asio/doc/quickref.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- quickref.xml 22 Apr 2007 22:26:40 -0000 1.3
+++ quickref.xml 16 May 2007 14:35:08 -0000 1.4
@@ -9,7 +9,7 @@
-->
<informaltable frame="all">
- <tgroup cols="3">
+ <tgroup cols="4">
<tbody>
<row>
<entry valign="top">
@@ -84,6 +84,9 @@
<bridgehead renderas="sect3">Free Functions</bridgehead>
<itemizedlist>
<listitem><link
linkend="boost_asio.reference.add_service">add_service</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.asio_handler_allocate">asio_handler_allocate</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.asio_handler_deallocate">asio_handler_deallocate</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.asio_handler_invoke">asio_handler_invoke</link></listitem>
<listitem><link
linkend="boost_asio.reference.async_read">async_read</link></listitem>
<listitem><link
linkend="boost_asio.reference.async_read_until">async_read_until</link></listitem>
<listitem><link
linkend="boost_asio.reference.async_write">async_write</link></listitem>
@@ -95,12 +98,53 @@
<listitem><link
linkend="boost_asio.reference.use_service">use_service</link></listitem>
<listitem><link
linkend="boost_asio.reference.write">write</link></listitem>
</itemizedlist>
+ <bridgehead renderas="sect3">Error Codes</bridgehead>
+ <itemizedlist>
+ <listitem><link
linkend="boost_asio.reference.error">error</link></listitem>
+ </itemizedlist>
<bridgehead renderas="sect3">Type Traits</bridgehead>
<itemizedlist>
<listitem><link
linkend="boost_asio.reference.is_read_buffered">is_read_buffered</link></listitem>
<listitem><link
linkend="boost_asio.reference.is_write_buffered">is_write_buffered</link></listitem>
</itemizedlist>
</entry>
+ <entry valign="top">
+ <bridgehead renderas="sect3">Type Requirements</bridgehead>
+ <itemizedlist>
+ <listitem><link
linkend="boost_asio.reference.asynchronous_operations">Asynchronous
operations</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.AcceptHandler">AcceptHandler</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.AsyncReadStream">AsyncReadStream</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.AsyncWriteStream">AsyncWriteStream</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.CompletionHandler">CompletionHandler</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.ConnectHandler">ConnectHandler</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.ConstBufferSequence">ConstBufferSequence</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.ConvertibleToConstBuffer">ConvertibleToConstBuffer</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.ConvertibleToMutableBuffer">ConvertibleToMutableBuffer</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.DatagramSocketService">DatagramSocketService</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.Endpoint">Endpoint</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.GettableSocketOption">GettableSocketOption</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.Handler">Handler</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.InternetProtocol">InternetProtocol</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.IoControlCommand">IoControlCommand</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.IoObjectService">IoObjectService</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.MutableBufferSequence">MutableBufferSequence</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.Protocol">Protocol</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.ReadHandler">ReadHandler</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.ResolveHandler">ResolveHandler</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.ResolverService">ResolverService</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.Service">Service</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.SettableSocketOption">SettableSocketOption</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.SocketAcceptorService">SocketAcceptorService</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.SocketService">SocketService</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.StreamSocketService">StreamSocketService</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.SyncReadStream">SyncReadStream</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.SyncWriteStream">SyncWriteStream</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.TimerService">TimerService</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.TimeTraits">TimeTraits</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.WaitHandler">WaitHandler</link></listitem>
+ <listitem><link
linkend="boost_asio.reference.WriteHandler">WriteHandler</link></listitem>
+ </itemizedlist>
+ </entry>
</row>
</tbody>
</tgroup>
Index: reference.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/asio/doc/reference.qbk,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -d -r1.8 -r1.9
--- reference.qbk 12 May 2007 10:52:21 -0000 1.8
+++ reference.qbk 16 May 2007 14:35:08 -0000 1.9
@@ -7,6 +7,41 @@
[section:reference Reference]
+[xinclude quickref.xml]
+
+[include requirements/asynchronous_operations.qbk]
+[include requirements/AcceptHandler.qbk]
+[include requirements/AsyncReadStream.qbk]
+[include requirements/AsyncWriteStream.qbk]
+[include requirements/CompletionHandler.qbk]
+[include requirements/ConnectHandler.qbk]
+[include requirements/ConstBufferSequence.qbk]
+[include requirements/ConvertibleToConstBuffer.qbk]
+[include requirements/ConvertibleToMutableBuffer.qbk]
+[include requirements/DatagramSocketService.qbk]
+[include requirements/Endpoint.qbk]
+[include requirements/GettableSocketOption.qbk]
+[include requirements/Handler.qbk]
+[include requirements/InternetProtocol.qbk]
+[include requirements/IoControlCommand.qbk]
+[include requirements/IoObjectService.qbk]
+[include requirements/MutableBufferSequence.qbk]
+[include requirements/Protocol.qbk]
+[include requirements/ReadHandler.qbk]
+[include requirements/ResolveHandler.qbk]
+[include requirements/ResolverService.qbk]
+[include requirements/Service.qbk]
+[include requirements/SettableSocketOption.qbk]
+[include requirements/SocketAcceptorService.qbk]
+[include requirements/SocketService.qbk]
+[include requirements/StreamSocketService.qbk]
+[include requirements/SyncReadStream.qbk]
+[include requirements/SyncWriteStream.qbk]
+[include requirements/TimeTraits.qbk]
+[include requirements/TimerService.qbk]
+[include requirements/WaitHandler.qbk]
+[include requirements/WriteHandler.qbk]
+
[section:add_service add_service]
Index: reference.xsl
===================================================================
RCS file: /cvsroot/boost/boost/libs/asio/doc/reference.xsl,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- reference.xsl 22 Apr 2007 09:34:39 -0000 1.3
+++ reference.xsl 16 May 2007 14:35:08 -0000 1.4
@@ -33,6 +33,41 @@
[section:reference Reference]
+[xinclude quickref.xml]
+
+[include requirements/asynchronous_operations.qbk]
+[include requirements/AcceptHandler.qbk]
+[include requirements/AsyncReadStream.qbk]
+[include requirements/AsyncWriteStream.qbk]
+[include requirements/CompletionHandler.qbk]
+[include requirements/ConnectHandler.qbk]
+[include requirements/ConstBufferSequence.qbk]
+[include requirements/ConvertibleToConstBuffer.qbk]
+[include requirements/ConvertibleToMutableBuffer.qbk]
+[include requirements/DatagramSocketService.qbk]
+[include requirements/Endpoint.qbk]
+[include requirements/GettableSocketOption.qbk]
+[include requirements/Handler.qbk]
+[include requirements/InternetProtocol.qbk]
+[include requirements/IoControlCommand.qbk]
+[include requirements/IoObjectService.qbk]
+[include requirements/MutableBufferSequence.qbk]
+[include requirements/Protocol.qbk]
+[include requirements/ReadHandler.qbk]
+[include requirements/ResolveHandler.qbk]
+[include requirements/ResolverService.qbk]
+[include requirements/Service.qbk]
+[include requirements/SettableSocketOption.qbk]
+[include requirements/SocketAcceptorService.qbk]
+[include requirements/SocketService.qbk]
+[include requirements/StreamSocketService.qbk]
+[include requirements/SyncReadStream.qbk]
+[include requirements/SyncWriteStream.qbk]
+[include requirements/TimeTraits.qbk]
+[include requirements/TimerService.qbk]
+[include requirements/WaitHandler.qbk]
+[include requirements/WriteHandler.qbk]
+
</xsl:text>
<xsl:for-each select="
Index: tutorial.qbk
===================================================================
RCS file: /cvsroot/boost/boost/libs/asio/doc/tutorial.qbk,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- tutorial.qbk 22 Apr 2007 09:34:39 -0000 1.3
+++ tutorial.qbk 16 May 2007 14:35:08 -0000 1.4
@@ -30,7 +30,7 @@
[heading Introduction to Sockets]
-The tutorial programs in this section show how to use asio to develop simple
client and server programs. These tutorial programs are based around the [EMAIL
PROTECTED]://www.ietf.org/rfc/rfc867.txt daytime] protocol, which supports both
TCP and UDP.
+The tutorial programs in this section show how to use asio to develop simple
client and server programs. These tutorial programs are based around the
daytime protocol, which supports both TCP and UDP.
The first three tutorial programs implement the daytime protocol using TCP.
--- requirements.qbk DELETED ---
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Boost-cvs mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/boost-cvs
