doc/html/boost_asio/overview/core/basics.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Basic Boost.Asio Anatomy</title>
   5 <link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../../../boost_asio.html" title="Boost.Asio">
   8 <link rel="up" href="../core.html" title="Core Concepts and Functionality">
   9 <link rel="prev" href="../core.html" title="Core Concepts and Functionality">
  10 <link rel="next" href="async.html" title="The Proactor Design Pattern: Concurrency Without Threads">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="../core.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="async.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h4 class="title">
  27 <a name="boost_asio.overview.core.basics"></a><a class="link" href="basics.html" title="Basic Boost.Asio Anatomy">Basic Boost.Asio Anatomy</a>
  28 </h4></div></div></div>
  29 <p>
  30           Boost.Asio may be used to perform both synchronous and asynchronous operations
  31           on I/O objects such as sockets. Before using Boost.Asio it may be useful
  32           to get a conceptual picture of the various parts of Boost.Asio, your program,
  33           and how they work together.
  34         </p>
  35 <p>
  36           As an introductory example, let's consider what happens when you perform
  37           a connect operation on a socket. We shall start by examining synchronous
  38           operations.
  39         </p>
  40 <p>
  41           <span class="inlinemediaobject"><img src="../../sync_op.png" alt="sync_op"></span>
  42         </p>
  43 <p>
  44           <span class="bold"><strong>Your program</strong></span> will have at least one <span class="bold"><strong>io_service</strong></span> object. The <span class="bold"><strong>io_service</strong></span>
  45           represents <span class="bold"><strong>your program</strong></span>'s link to the
  46           <span class="bold"><strong>operating system</strong></span>'s I/O services.
  47         </p>
  48 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_service</span> <span class="identifier">io_service</span><span class="special">;</span>
  49 </pre>
  50 <p>
  51           To perform I/O operations <span class="bold"><strong>your program</strong></span>
  52           will need an <span class="bold"><strong>I/O object</strong></span> such as a TCP
  53           socket:
  54         </p>
  55 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">ip</span><span class="special">::</span><span class="identifier">tcp</span><span class="special">::</span><span class="identifier">socket</span> <span class="identifier">socket</span><span class="special">(</span><span class="identifier">io_service</span><span class="special">);</span>
  56 </pre>
  57 <p>
  58           When a synchronous connect operation is performed, the following sequence
  59           of events occurs:
  60         </p>
  61 <p>
  62           1. <span class="bold"><strong>Your program</strong></span> initiates the connect
  63           operation by calling the <span class="bold"><strong>I/O object</strong></span>:
  64         </p>
  65 <pre class="programlisting"><span class="identifier">socket</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">server_endpoint</span><span class="special">);</span>
  66 </pre>
  67 <p>
  68           2. The <span class="bold"><strong>I/O object</strong></span> forwards the request
  69           to the <span class="bold"><strong>io_service</strong></span>.
  70         </p>
  71 <p>
  72           3. The <span class="bold"><strong>io_service</strong></span> calls on the <span class="bold"><strong>operating system</strong></span> to perform the connect operation.
  73         </p>
  74 <p>
  75           4. The <span class="bold"><strong>operating system</strong></span> returns the result
  76           of the operation to the <span class="bold"><strong>io_service</strong></span>.
  77         </p>
  78 <p>
  79           5. The <span class="bold"><strong>io_service</strong></span> translates any error
  80           resulting from the operation into an object of type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span></code>.
  81           An <code class="computeroutput"><span class="identifier">error_code</span></code> may be compared
  82           with specific values, or tested as a boolean (where a <code class="computeroutput"><span class="keyword">false</span></code>
  83           result means that no error occurred). The result is then forwarded back
  84           up to the <span class="bold"><strong>I/O object</strong></span>.
  85         </p>
  86 <p>
  87           6. The <span class="bold"><strong>I/O object</strong></span> throws an exception
  88           of type <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">system_error</span></code> if the operation failed.
  89           If the code to initiate the operation had instead been written as:
  90         </p>
  91 <pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">;</span>
  92 <span class="identifier">socket</span><span class="special">.</span><span class="identifier">connect</span><span class="special">(</span><span class="identifier">server_endpoint</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">);</span>
  93 </pre>
  94 <p>
  95           then the <code class="computeroutput"><span class="identifier">error_code</span></code> variable
  96           <code class="computeroutput"><span class="identifier">ec</span></code> would be set to the
  97           result of the operation, and no exception would be thrown.
  98         </p>
  99 <p>
 100           When an asynchronous operation is used, a different sequence of events
 101           occurs.
 102         </p>
 103 <p>
 104           <span class="inlinemediaobject"><img src="../../async_op1.png" alt="async_op1"></span>
 105         </p>
 106 <p>
 107           1. <span class="bold"><strong>Your program</strong></span> initiates the connect
 108           operation by calling the <span class="bold"><strong>I/O object</strong></span>:
 109         </p>
 110 <pre class="programlisting"><span class="identifier">socket</span><span class="special">.</span><span class="identifier">async_connect</span><span class="special">(</span><span class="identifier">server_endpoint</span><span class="special">,</span> <span class="identifier">your_completion_handler</span><span class="special">);</span>
 111 </pre>
 112 <p>
 113           where <code class="computeroutput"><span class="identifier">your_completion_handler</span></code>
 114           is a function or function object with the signature:
 115         </p>
 116 <pre class="programlisting"><span class="keyword">void</span> <span class="identifier">your_completion_handler</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">system</span><span class="special">::</span><span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">);</span>
 117 </pre>
 118 <p>
 119           The exact signature required depends on the asynchronous operation being
 120           performed. The reference documentation indicates the appropriate form for
 121           each operation.
 122         </p>
 123 <p>
 124           2. The <span class="bold"><strong>I/O object</strong></span> forwards the request
 125           to the <span class="bold"><strong>io_service</strong></span>.
 126         </p>
 127 <p>
 128           3. The <span class="bold"><strong>io_service</strong></span> signals to the <span class="bold"><strong>operating system</strong></span> that it should start an asynchronous
 129           connect.
 130         </p>
 131 <p>
 132           Time passes. (In the synchronous case this wait would have been contained
 133           entirely within the duration of the connect operation.)
 134         </p>
 135 <p>
 136           <span class="inlinemediaobject"><img src="../../async_op2.png" alt="async_op2"></span>
 137         </p>
 138 <p>
 139           4. The <span class="bold"><strong>operating system</strong></span> indicates that
 140           the connect operation has completed by placing the result on a queue, ready
 141           to be picked up by the <span class="bold"><strong>io_service</strong></span>.
 142         </p>
 143 <p>
 144           5. <span class="bold"><strong>Your program</strong></span> must make a call to <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>
 145           (or to one of the similar <span class="bold"><strong>io_service</strong></span> member
 146           functions) in order for the result to be retrieved. A call to <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>
 147           blocks while there are unfinished asynchronous operations, so you would
 148           typically call it as soon as you have started your first asynchronous operation.
 149         </p>
 150 <p>
 151           6. While inside the call to <code class="computeroutput"><span class="identifier">io_service</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, the <span class="bold"><strong>io_service</strong></span>
 152           dequeues the result of the operation, translates it into an <code class="computeroutput"><span class="identifier">error_code</span></code>, and then passes it to <span class="bold"><strong>your completion handler</strong></span>.
 153         </p>
 154 <p>
 155           This is a simplified picture of how Boost.Asio operates. You will want
 156           to delve further into the documentation if your needs are more advanced,
 157           such as extending Boost.Asio to perform other types of asynchronous operations.
 158         </p>
 159 </div>
 160 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 161 <td align="left"></td>
 162 <td align="right"><div class="copyright-footer">Copyright &#169; 2003-2014 Christopher M. Kohlhoff<p>
 163         Distributed under the Boost Software License, Version 1.0. (See accompanying
 164         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
 165       </p>
 166 </div></td>
 167 </tr></table>
 168 <hr>
 169 <div class="spirit-nav">
 170 <a accesskey="p" href="../core.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../core.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../boost_asio.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="async.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 171 </div>
 172 </body>
 173 </html>