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

From: chris_at_[hidden]
Date: 2008-07-18 09:18:57

Author: chris_kohlhoff
Date: 2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
New Revision: 47550
URL: http://svn.boost.org/trac/boost/changeset/47550

Log:
More documentation updates.

Added:
   trunk/libs/asio/doc/overview/async_op1.dot   (contents, props changed)
   trunk/libs/asio/doc/overview/async_op1.png   (contents, props changed)
   trunk/libs/asio/doc/overview/async_op2.dot   (contents, props changed)
   trunk/libs/asio/doc/overview/async_op2.png   (contents, props changed)
   trunk/libs/asio/doc/overview/basics.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/protocols.qbk   (contents, props changed)
   trunk/libs/asio/doc/overview/sync_op.dot   (contents, props changed)
   trunk/libs/asio/doc/overview/sync_op.png   (contents, props changed)
Text files modified: 
   trunk/libs/asio/doc/Jamfile.v2   |     6 ++++++                                  
   trunk/libs/asio/doc/overview.qbk |    12 ++++++------                            
   2 files changed, 12 insertions(+), 6 deletions(-)

Modified: trunk/libs/asio/doc/Jamfile.v2
==============================================================================
--- trunk/libs/asio/doc/Jamfile.v2	(original)
+++ trunk/libs/asio/doc/Jamfile.v2	2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
@@ -25,6 +25,9 @@
 install images
   :
     overview/proactor.png
+    overview/sync_op.png
+    overview/async_op1.png
+    overview/async_op2.png
   :
     <location>html/boost_asio
   ;
@@ -67,6 +70,9 @@
 install asio_doc_images
   :
     overview/proactor.png
+    overview/sync_op.png
+    overview/async_op1.png
+    overview/async_op2.png
   :
     <location>$(BOOST_ROOT)/doc/html/boost_asio
   ;

Modified: trunk/libs/asio/doc/overview.qbk
==============================================================================
--- trunk/libs/asio/doc/overview.qbk	(original)
+++ trunk/libs/asio/doc/overview.qbk	2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
@@ -9,6 +9,7 @@
 
 * [link boost_asio.overview.rationale Rationale]
 * [link boost_asio.overview.core Core Concepts and Functionality]
+  * [link boost_asio.overview.core.basics Basic Boost.Asio Anatomy]
   * [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]
@@ -18,14 +19,9 @@
   * [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.protocols TCP, UDP and ICMP]
   * [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]
@@ -41,6 +37,7 @@
 
 [section:core Core Concepts and Functionality]
 
+* [link boost_asio.overview.core.basics Basic Boost.Asio Anatomy]
 * [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]
@@ -50,6 +47,7 @@
 * [link boost_asio.overview.core.line_based Line-Based Operations]
 * [link boost_asio.overview.core.allocation Custom Memory Allocation]
 
+[include overview/basics.qbk]
 [include overview/async.qbk]
 [include overview/threads.qbk]
 [include overview/strands.qbk]
@@ -63,9 +61,11 @@
 
 [section:networking Networking]
 
+* [link boost_asio.overview.networking.protocols TCP, UDP and ICMP]
 * [link boost_asio.overview.networking.iostreams Socket Iostreams]
 * [link boost_asio.overview.networking.bsd_sockets The BSD Socket API and Boost.Asio]
 
+[include overview/protocols.qbk]
 [include overview/iostreams.qbk]
 [include overview/bsd_sockets.qbk]
 

Added: trunk/libs/asio/doc/overview/async_op1.dot
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/async_op1.dot	2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
@@ -0,0 +1,78 @@
+digraph g
+{
+  graph
+    [
+      nodesep="0.2"
+    ];
+
+  edge
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      labelfontname="Helvetica",
+      labelfontsize=10
+    ];
+
+  node
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      shape=box
+    ];
+
+  edge
+    [
+      arrowhead="open"
+    ]
+
+  // Program elements.
+  {
+    operating_system [ label="Operating System", shape=ellipse ];
+    io_service [ label="io_service" ];
+    io_object [ label="I/O Object\ne.g. socket" ];
+    your_program [ label="Your Program" ];
+    your_completion_handler [ label="Your Completion Handler" ];
+  }
+
+  // Owning relationships.
+  {
+    edge [ arrowtail="diamond" ];
+    your_program:e -> your_completion_handler:n;
+    your_program:w -> io_object:nw;
+    your_program:se -> io_service:ne;
+  }
+
+  // Non-owning relationships;
+  {
+    io_object:sw -> io_service:w;
+  }
+
+  // Visible actions.
+  {
+    edge [ style="dashed", color="#808080" ];
+
+    // Forward actions.
+    {
+      your_program:sw -> io_object:n [ label="1" ];
+      io_object:s -> io_service:nw [ label="2" ];
+      io_service:s -> operating_system:n [ label="3" ];
+    }
+  }
+
+  // Invisible actions.
+  {
+    edge [ style="invis" ];
+
+    // Forward actions.
+    {
+      your_program:s -> io_service:n [ label="5" ];
+    }
+
+    // Reverse actions.
+    {
+      edge [ arrowhead="none", arrowtail="open" ];
+      //io_service:s -> operating_system:n [ label="4" ];
+      your_completion_handler:s -> io_service:e [ label="6" ];
+    }
+  }
+}

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

Added: trunk/libs/asio/doc/overview/async_op2.dot
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/async_op2.dot	2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
@@ -0,0 +1,78 @@
+digraph g
+{
+  graph
+    [
+      nodesep="0.2"
+    ];
+
+  edge
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      labelfontname="Helvetica",
+      labelfontsize=10
+    ];
+
+  node
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      shape=box
+    ];
+
+  edge
+    [
+      arrowhead="open"
+    ]
+
+  // Program elements.
+  {
+    operating_system [ label="Operating System", shape=ellipse ];
+    io_service [ label="io_service" ];
+    io_object [ label="I/O Object\ne.g. socket" ];
+    your_program [ label="Your Program" ];
+    your_completion_handler [ label="Your Completion Handler" ];
+  }
+
+  // Owning relationships.
+  {
+    edge [ arrowtail="diamond" ];
+    your_program:e -> your_completion_handler:n;
+    your_program:w -> io_object:nw;
+    your_program:se -> io_service:ne;
+  }
+
+  // Non-owning relationships;
+  {
+    io_object:sw -> io_service:w;
+  }
+
+  // Visible actions.
+  {
+    edge [ style="dashed", color="#808080" ];
+
+    // Forward actions.
+    {
+      your_program:s -> io_service:n [ label="5" ];
+    }
+
+    // Reverse actions.
+    {
+      edge [ arrowhead="none", arrowtail="open" ];
+      io_service:s -> operating_system:n [ label="4" ];
+      your_completion_handler:s -> io_service:e [ label="6" ];
+    }
+  }
+
+  // Invisible actions.
+  {
+    edge [ style="invis" ];
+
+    // Forward actions.
+    {
+      your_program:sw -> io_object:n [ label="1" ];
+      io_object:s -> io_service:nw [ label="2" ];
+      //io_service:s -> operating_system:n [ label="3" ];
+    }
+  }
+}

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

Added: trunk/libs/asio/doc/overview/basics.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/basics.qbk	2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
@@ -0,0 +1,106 @@
+[/
+ / 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:basics Basic Boost.Asio Anatomy]
+
+Boost.Asio may be used to perform both synchronous and asynchronous operations on I/O
+objects such as sockets. Before using Boost.Asio it may be useful to get a conceptual
+picture of the various parts of Boost.Asio, your program, and how they work together.
+
+As an introductory example, let's consider what happens when you perform a
+connect operation on a socket. We shall start by examining synchronous
+operations.
+
+[$boost_asio/sync_op.png]
+
+[*Your program] will have at least one [*io_service] object. The [*io_service]
+represents [*your program]'s link to the [*operating system]'s I/O services.
+
+  boost::asio::io_service io_service;
+
+To perform I/O operations [*your program] will need an [*I/O object] such as a
+TCP socket:
+
+  boost::asio::ip::tcp::socket socket(io_service);
+
+When a synchronous connect operation is performed, the following sequence of
+events occurs:
+
+1. [*Your program] initiates the connect operation by calling the [*I/O
+object]:
+
+  socket.connect(server_endpoint);
+
+2. The [*I/O object] forwards the request to the [*io_service].
+
+3. The [*io_service] calls on the [*operating system] to perform the connect
+operation.
+
+4. The [*operating system] returns the result of the operation to the
+[*io_service].
+
+5. The [*io_service] translates any error resulting from the operation into a
+`boost::system::error_code`. An `error_code` may be compared with specific
+values, or tested as a boolean (where a `false` result means that no error
+occurred). The result is then forwarded back up to the [*I/O object].
+
+6. The [*I/O object] throws an exception of type `boost::system::system_error`
+if the operation failed. If the code to initiate the operation had instead been
+written as:
+
+  boost::system::error_code ec;
+  socket.connect(server_endpoint, ec);
+
+then the `error_code` variable `ec` would be set to the result of the
+operation, and no exception would be thrown.
+
+When an asynchronous operation is used, a different sequence of events occurs.
+
+[$boost_asio/async_op1.png]
+
+1. [*Your program] initiates the connect operation by calling the [*I/O
+object]:
+
+  socket.async_connect(server_endpoint, your_completion_handler);
+
+where `your_completion_handler` is a function or function object with the
+signature:
+
+  void your_completion_handler(const boost::system::error_code& ec);
+
+The exact signature required depends on the asynchronous operation being
+performed. The reference documentation indicates the appropriate form for each
+operation.
+
+2. The [*I/O object] forwards the request to the [*io_service].
+
+3. The [*io_service] signals to the [*operating system] that it should start an
+asynchronous connect.
+
+Time passes. (In the synchronous case this wait would have been contained
+entirely within the duration of the connect operation.)
+
+[$boost_asio/async_op2.png]
+
+4. The [*operating system] indicates that the connect operation has completed
+by placing the result on a queue, ready to be picked up by the [*io_service].
+
+5. [*Your program] must make a call to `io_service::run()` (or to one of the
+similar [*io_service] member functions) in order for the result to be
+retrieved. A call to `io_service::run()` blocks while there are unfinished
+asynchronous operations, so you would typically call it as soon as you have
+started your first asynchronous operation.
+
+6. While inside the call to `io_service::run()`, the [*io_service] dequeues the
+result of the operation, translates it into an `error_code`, and then passes it
+to [*your completion handler].
+
+This is a simplified picture of how Boost.Asio operates. You will want to delve
+further into the documentation if you needs are more advanced, such as
+extending Boost.Asio to perform other types of asynchronous operations.
+
+[endsect]

Added: trunk/libs/asio/doc/overview/protocols.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/protocols.qbk	2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
@@ -0,0 +1,128 @@
+[/
+ / 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:protocols TCP, UDP and ICMP]
+
+Boost.Asio provides off-the-shelf support for the internet protocols TCP, UDP and
+ICMP.
+
+[heading TCP Clients]
+
+Hostname resolution is performed using a resolver, where host and service names
+are looked up and converted into one or more endpoints:
+
+  ip::tcp::resolver resolver(my_io_service);
+  ip::tcp::resolver::query query("www.boost.org", "http");
+  ip::tcp::resolver::iterator iter = resolver.resolve(query);
+  ip::tcp::resolver::iterator end; // End marker.
+  while (iter != end)
+  {
+    ip::tcp::endpoint endpoint = *iter++;
+    std::cout << endpoint << std::endl;
+  }
+
+The list of endpoints obtained above could contain both IPv4 and IPv6 endpoints,
+so a program may try each of them until it finds one that works. This keeps the
+client program independent of a specific IP version.
+
+When an endpoint is available, a socket can be created and connected:
+
+  ip::tcp::socket socket(my_io_service);
+  socket.connect(endpoint);
+
+Data may be read from or written to a connected TCP socket using the [link
+boost_asio.reference.basic_stream_socket.receive receive()], [link
+boost_asio.reference.basic_stream_socket.async_receive async_receive()], [link
+boost_asio.reference.basic_stream_socket.send send()] or [link
+boost_asio.reference.basic_stream_socket.async_send async_send()] member functions.
+However, as these could result in [link boost_asio.overview.core.streams short writes
+or reads], an application will typically use the following operations instead:
+[link boost_asio.reference.read read()], [link boost_asio.reference.async_read
+async_read()], [link boost_asio.reference.write write()] and [link
+boost_asio.reference.async_write async_write()].
+
+[heading TCP Servers]
+
+A program uses an acceptor to accept incoming TCP connections:
+
+  ip::tcp::acceptor acceptor(my_io_service, my_endpoint);
+  ...
+  ip::tcp::socket socket(my_io_service);
+  acceptor.accept(socket);
+
+After a socket has been successfully accepted, it may be read from or written
+to as illustrated for TCP clients above.
+
+[heading UDP]
+
+UDP hostname resolution is also performed using a resolver:
+
+  ip::udp::resolver resolver(my_io_service);
+  ip::udp::resolver::query query("localhost", "daytime");
+  ip::udp::resolver::iterator iter = resolver.resolve(query);
+  ...
+
+A UDP socket is typically bound to a local endpoint. The following code will
+create an IP version 4 UDP socket and bind it to the "any" address on port
+`12345`:
+
+  ip::udp::endpoint endpoint(ip::udp::v4(), 12345);
+  ip::udp::socket socket(my_io_service, endpoint);
+
+Data may be read from or written to an unconnected UDP socket using the [link
+boost_asio.reference.basic_datagram_socket.receive_from receive_from()], [link
+boost_asio.reference.basic_datagram_socket.async_receive_from async_receive_from()],
+[link boost_asio.reference.basic_datagram_socket.send_to send_to()] or [link
+boost_asio.reference.basic_datagram_socket.async_send_to async_send_to()] member
+functions. For a connected UDP socket, use the [link
+boost_asio.reference.basic_datagram_socket.receive receive()], [link
+boost_asio.reference.basic_datagram_socket.async_receive async_receive()], [link
+boost_asio.reference.basic_datagram_socket.send send()] or [link
+boost_asio.reference.basic_datagram_socket.async_send async_send()] member functions.
+
+[heading ICMP]
+
+As with TCP and UDP, ICMP hostname resolution is performed using a resolver:
+
+  ip::icmp::resolver resolver(my_io_service);
+  ip::icmp::resolver::query query("localhost", "daytime");
+  ip::icmp::resolver::iterator iter = resolver.resolve(query);
+  ...
+
+An ICMP socket may be bound to a local endpoint. The following code will create
+an IP version 6 ICMP socket and bind it to the "any" address:
+
+  ip::icmp::endpoint endpoint(ip::icmp::v6(), 0);
+  ip::icmp::socket socket(my_io_service, endpoint);
+
+The port number is not used for ICMP.
+
+Data may be read from or written to an unconnected ICMP socket using the [link
+boost_asio.reference.basic_raw_socket.receive_from receive_from()], [link
+boost_asio.reference.basic_raw_socket.async_receive_from async_receive_from()],
+[link boost_asio.reference.basic_raw_socket.send_to send_to()] or [link
+boost_asio.reference.basic_raw_socket.async_send_to async_send_to()] member
+functions. For a connected ICMP socket, use the [link
+boost_asio.reference.basic_raw_socket.receive receive()], [link
+boost_asio.reference.basic_raw_socket.async_receive async_receive()], [link
+boost_asio.reference.basic_raw_socket.send send()] or [link
+boost_asio.reference.basic_raw_socket.async_send async_send()] member functions.
+
+[heading Other Protocols]
+
+Support for other socket protocols (such as Bluetooth or IRCOMM sockets) can be
+added by implementing the [link boost_asio.reference.Protocol Protocol] type
+requirements.
+
+[heading See Also]
+
+[link boost_asio.reference.ip__tcp ip::tcp],
+[link boost_asio.reference.ip__udp ip::udp],
+[link boost_asio.reference.ip__icmp ip::icmp],
+[link boost_asio.tutorial.tutdaytime1 daytime protocol tutorials].
+
+[endsect]

Added: trunk/libs/asio/doc/overview/sync_op.dot
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/overview/sync_op.dot	2008-07-18 09:18:56 EDT (Fri, 18 Jul 2008)
@@ -0,0 +1,67 @@
+digraph g
+{
+  graph
+    [
+      nodesep="0.6"
+    ];
+
+  edge
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      labelfontname="Helvetica",
+      labelfontsize=10
+    ];
+
+  node
+    [
+      fontname="Helvetica",
+      fontsize=10,
+      shape=box
+    ];
+
+  edge
+    [
+      arrowhead="open"
+    ]
+
+  // Program elements.
+  {
+    operating_system [ label="Operating System", shape=ellipse ];
+    io_service [ label="io_service" ];
+    io_object [ label="I/O Object\ne.g. socket" ];
+    your_program [ label="Your Program" ];
+  }
+
+  // Owning relationships.
+  {
+    edge [ arrowtail="diamond" ];
+    your_program:w -> io_object:nw;
+    your_program:se -> io_service:ne;
+  }
+
+  // Non-owning relationships;
+  {
+    io_object:sw -> io_service:w;
+  }
+
+  // Actions.
+  {
+    edge [ style="dashed", color="#808080" ];
+
+    // Forward actions.
+    {
+      your_program:sw -> io_object:n [ label="1" ];
+      io_object:s -> io_service:nw [ label="2" ];
+      io_service:sw -> operating_system:nw [ label="3" ];
+    }
+
+    // Reverse actions.
+    {
+      edge [ arrowhead="none", arrowtail="open" ];
+      io_service:se -> operating_system:ne [ label="4" ];
+      io_object:se -> io_service:n [ label="5" ];
+      your_program:s -> io_object:ne [ label="6" ];
+    }
+  }
+}

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