1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 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.79.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>I/O execution context</strong></span>, such as an <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">io_context</span></code> object, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">thread_pool</span></code> 45 object, or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">system_context</span></code>. This <span class="bold"><strong>I/O 46 execution context</strong></span> represents <span class="bold"><strong>your program</strong></span>'s 47 link to the <span class="bold"><strong>operating system</strong></span>'s I/O services. 48 </p> 49<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_context</span> <span class="identifier">io_context</span><span class="special">;</span> 50</pre> 51<p> 52 To perform I/O operations <span class="bold"><strong>your program</strong></span> 53 will need an <span class="bold"><strong>I/O object</strong></span> such as a TCP 54 socket: 55 </p> 56<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_context</span><span class="special">);</span> 57</pre> 58<p> 59 When a synchronous connect operation is performed, the following sequence 60 of events occurs: 61 </p> 62<p> 63 1. <span class="bold"><strong>Your program</strong></span> initiates the connect 64 operation by calling the <span class="bold"><strong>I/O object</strong></span>: 65 </p> 66<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> 67</pre> 68<p> 69 2. The <span class="bold"><strong>I/O object</strong></span> forwards the request 70 to the <span class="bold"><strong>I/O execution context</strong></span>. 71 </p> 72<p> 73 3. The <span class="bold"><strong>I/O execution context</strong></span> calls on 74 the <span class="bold"><strong>operating system</strong></span> to perform the connect 75 operation. 76 </p> 77<p> 78 4. The <span class="bold"><strong>operating system</strong></span> returns the result 79 of the operation to the <span class="bold"><strong>I/O execution context</strong></span>. 80 </p> 81<p> 82 5. The <span class="bold"><strong>I/O execution context</strong></span> translates 83 any error 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>. An <code class="computeroutput"><span class="identifier">error_code</span></code> 84 may be compared with specific values, or tested as a boolean (where a 85 <code class="computeroutput"><span class="keyword">false</span></code> result means that no 86 error occurred). The result is then forwarded back up to the <span class="bold"><strong>I/O object</strong></span>. 87 </p> 88<p> 89 6. The <span class="bold"><strong>I/O object</strong></span> throws an exception 90 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. 91 If the code to initiate the operation had instead been written as: 92 </p> 93<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> 94<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> 95</pre> 96<p> 97 then the <code class="computeroutput"><span class="identifier">error_code</span></code> variable 98 <code class="computeroutput"><span class="identifier">ec</span></code> would be set to the 99 result of the operation, and no exception would be thrown. 100 </p> 101<p> 102 When an asynchronous operation is used, a different sequence of events 103 occurs. 104 </p> 105<p> 106 <span class="inlinemediaobject"><img src="../../async_op1.png" alt="async_op1"></span> 107 </p> 108<p> 109 1. <span class="bold"><strong>Your program</strong></span> initiates the connect 110 operation by calling the <span class="bold"><strong>I/O object</strong></span>: 111 </p> 112<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> 113</pre> 114<p> 115 where <code class="computeroutput"><span class="identifier">your_completion_handler</span></code> 116 is a function or function object with the signature: 117 </p> 118<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">&</span> <span class="identifier">ec</span><span class="special">);</span> 119</pre> 120<p> 121 The exact signature required depends on the asynchronous operation being 122 performed. The reference documentation indicates the appropriate form for 123 each operation. 124 </p> 125<p> 126 2. The <span class="bold"><strong>I/O object</strong></span> forwards the request 127 to the <span class="bold"><strong>I/O execution context</strong></span>. 128 </p> 129<p> 130 3. The <span class="bold"><strong>I/O execution context</strong></span> signals to 131 the <span class="bold"><strong>operating system</strong></span> that it should start 132 an asynchronous connect. 133 </p> 134<p> 135 Time passes. (In the synchronous case this wait would have been contained 136 entirely within the duration of the connect operation.) 137 </p> 138<p> 139 <span class="inlinemediaobject"><img src="../../async_op2.png" alt="async_op2"></span> 140 </p> 141<p> 142 4. The <span class="bold"><strong>operating system</strong></span> indicates that 143 the connect operation has completed by placing the result on a queue, ready 144 to be picked up by the <span class="bold"><strong>I/O execution context</strong></span>. 145 </p> 146<p> 147 5. When using an <code class="computeroutput"><span class="identifier">io_context</span></code> 148 as the <span class="bold"><strong>I/O execution context</strong></span>, <span class="bold"><strong>your program</strong></span> must make a call to <code class="computeroutput"><span class="identifier">io_context</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code> (or to one of the similar <code class="computeroutput"><span class="identifier">io_context</span></code> member functions) in order 149 for the result to be retrieved. A call to <code class="computeroutput"><span class="identifier">io_context</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code> blocks while there are unfinished asynchronous 150 operations, so you would typically call it as soon as you have started 151 your first asynchronous operation. 152 </p> 153<p> 154 6. While inside the call to <code class="computeroutput"><span class="identifier">io_context</span><span class="special">::</span><span class="identifier">run</span><span class="special">()</span></code>, the <span class="bold"><strong>I/O execution 155 context</strong></span> dequeues the result of the operation, translates it 156 into an <code class="computeroutput"><span class="identifier">error_code</span></code>, and 157 then passes it to <span class="bold"><strong>your completion handler</strong></span>. 158 </p> 159<p> 160 This is a simplified picture of how Boost.Asio operates. You will want 161 to delve further into the documentation if your needs are more advanced, 162 such as extending Boost.Asio to perform other types of asynchronous operations. 163 </p> 164</div> 165<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 166<td align="left"></td> 167<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 168 Kohlhoff<p> 169 Distributed under the Boost Software License, Version 1.0. (See accompanying 170 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>) 171 </p> 172</div></td> 173</tr></table> 174<hr> 175<div class="spirit-nav"> 176<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> 177</div> 178</body> 179</html> 180
