1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Coroutines TS Support</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="spawn.html" title="Stackful Coroutines"> 10<link rel="next" href="../networking.html" title="Networking"> 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="spawn.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="../networking.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.coroutines_ts"></a><a class="link" href="coroutines_ts.html" title="Coroutines TS Support">Coroutines 28 TS Support</a> 29</h4></div></div></div> 30<p> 31 Support for the Coroutines TS is provided via the <a class="link" href="../../reference/awaitable.html" title="awaitable"><code class="computeroutput">awaitable</code></a> 32 class template, the <a class="link" href="../../reference/use_awaitable_t.html" title="use_awaitable_t"><code class="computeroutput">use_awaitable</code></a> 33 completion token, and the <a class="link" href="../../reference/co_spawn.html" title="co_spawn"><code class="computeroutput">co_spawn()</code></a> 34 function. These facilities allow programs to implement asynchronous logic 35 in a synchronous manner, in conjunction with the <code class="computeroutput">co_await</code> 36 keyword, as shown in the following example: 37 </p> 38<pre class="programlisting">boost::asio::co_spawn(executor, echo(std::move(socket)), boost::asio::detached); 39 40// ... 41 42boost::asio::awaitable<void> echo(tcp::socket socket) 43{ 44 try 45 { 46 char data[1024]; 47 for (;;) 48 { 49 std::size_t n = co_await socket.async_read_some(boost::asio::buffer(data), boost::asio::use_awaitable); 50 co_await async_write(socket, boost::asio::buffer(data, n), boost::asio::use_awaitable); 51 } 52 } 53 catch (std::exception& e) 54 { 55 std::printf("echo Exception: %s\n", e.what()); 56 } 57} 58</pre> 59<p> 60 The first argument to <code class="computeroutput">co_spawn()</code> is an <a class="link" href="../../reference/Executor1.html" title="Executor requirements">executor</a> 61 that determines the context in which the coroutine is permitted to execute. 62 For example, a server's per-client object may consist of multiple coroutines; 63 they should all run on the same <code class="computeroutput">strand</code> so that no explicit 64 synchronisation is required. 65 </p> 66<p> 67 The second argument is an <a class="link" href="../../reference/awaitable.html" title="awaitable"><code class="computeroutput">awaitable<R></code></a>, 68 that is the result of the coroutine's entry point function, and in the 69 above example is the result of the call to <code class="computeroutput">echo</code>. (Alternatively, 70 this argument can be a function object that returns the <a class="link" href="../../reference/awaitable.html" title="awaitable"><code class="computeroutput">awaitable<R></code></a>.) 71 The template parameter <code class="computeroutput">R</code> is the type of return value produced 72 by the coroutine. In the above example, the coroutine returns <code class="computeroutput">void</code>. 73 </p> 74<p> 75 The third argument is a completion token, and this is used by <code class="computeroutput">co_spawn()</code> 76 to produce a completion handler with signature <code class="computeroutput">void(std::exception_ptr, 77 R)</code>. This completion handler is invoked with the result of the coroutine 78 once it has finished. In the above example we pass a completion token type, 79 <a class="link" href="../../reference/detached.html" title="detached"><code class="computeroutput">boost::asio::detached</code></a>, 80 which is used to explicitly ignore the result of an asynchronous operation. 81 </p> 82<p> 83 In this example the body of the coroutine is implemented in the <code class="computeroutput">echo</code> 84 function. When the <code class="computeroutput">use_awaitable</code> completion token is passed 85 to an asynchronous operation, the operation's initiating function returns 86 an <code class="computeroutput">awaitable</code> that may be used with the <code class="computeroutput">co_await</code> 87 keyword: 88 </p> 89<pre class="programlisting">std::size_t n = co_await socket.async_read_some(boost::asio::buffer(data), boost::asio::use_awaitable); 90</pre> 91<p> 92 Where an asynchronous operation's handler signature has the form: 93 </p> 94<pre class="programlisting">void handler(boost::system::error_code ec, result_type result); 95</pre> 96<p> 97 the resulting type of the <code class="computeroutput">co_await</code> expression is <code class="computeroutput">result_type</code>. 98 In the <code class="computeroutput">async_read_some</code> example above, this is <code class="computeroutput">size_t</code>. 99 If the asynchronous operation fails, the <code class="computeroutput">error_code</code> is converted 100 into a <code class="computeroutput">system_error</code> exception and thrown. 101 </p> 102<p> 103 Where a handler signature has the form: 104 </p> 105<pre class="programlisting">void handler(boost::system::error_code ec); 106</pre> 107<p> 108 the <code class="computeroutput">co_await</code> expression produces a <code class="computeroutput">void</code> result. 109 As above, an error is passed back to the coroutine as a <code class="computeroutput">system_error</code> 110 exception. 111 </p> 112<h6> 113<a name="boost_asio.overview.core.coroutines_ts.h0"></a> 114 <span class="phrase"><a name="boost_asio.overview.core.coroutines_ts.see_also"></a></span><a class="link" href="coroutines_ts.html#boost_asio.overview.core.coroutines_ts.see_also">See 115 Also</a> 116 </h6> 117<p> 118 <a class="link" href="../../reference/co_spawn.html" title="co_spawn">co_spawn</a>, <a class="link" href="../../reference/detached.html" title="detached">detached</a>, 119 <a class="link" href="../../reference/redirect_error.html" title="redirect_error">redirect_error</a>, 120 <a class="link" href="../../reference/awaitable.html" title="awaitable">awaitable</a>, <a class="link" href="../../reference/use_awaitable_t.html" title="use_awaitable_t">use_awaitable_t</a>, 121 <a class="link" href="../../reference/use_awaitable.html" title="use_awaitable">use_awaitable</a>, 122 <a class="link" href="../../reference/this_coro__executor.html" title="this_coro::executor">this_coro::executor</a>, 123 <a class="link" href="../../examples/cpp17_examples.html#boost_asio.examples.cpp17_examples.coroutines_ts_support">Coroutines 124 TS examples</a>, <a class="link" href="spawn.html" title="Stackful Coroutines">Stackful 125 Coroutines</a>, <a class="link" href="coroutine.html" title="Stackless Coroutines">Stackless 126 Coroutines</a>. 127 </p> 128</div> 129<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 130<td align="left"></td> 131<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 132 Kohlhoff<p> 133 Distributed under the Boost Software License, Version 1.0. (See accompanying 134 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>) 135 </p> 136</div></td> 137</tr></table> 138<hr> 139<div class="spirit-nav"> 140<a accesskey="p" href="spawn.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="../networking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 141</div> 142</body> 143</html> 144
