3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>async_base</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="../../index.html" title="Chapter 1. Boost.Beast">
8 <link rel="up" href="../ref.html" title="This Page Intentionally Left Blank 2/2">
9 <link rel="prev" href="boost__beast__allocate_stable.html" title="allocate_stable">
10 <link rel="next" href="boost__beast__async_base/allocator_type.html" title="async_base::allocator_type">
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>
22 <div class="spirit-nav">
23 <a accesskey="p" href="boost__beast__allocate_stable.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost__beast__async_base/allocator_type.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h4 class="title">
27 <a name="beast.ref.boost__beast__async_base"></a><a class="link" href="boost__beast__async_base.html" title="async_base">async_base</a>
28 </h4></div></div></div>
30 Base class to assist writing composed operations.
33 <a name="beast.ref.boost__beast__async_base.h0"></a>
34 <span class="phrase"><a name="beast.ref.boost__beast__async_base.synopsis"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.synopsis">Synopsis</a>
37 Defined in header <code class="literal"><<a href="../../../../../../boost/beast/core/async_base.hpp" target="_top">boost/beast/core/async_base.hpp</a>></code>
39 <pre class="programlisting"><span class="keyword">template</span><span class="special"><</span>
40 <span class="keyword">class</span> <a href="../../../../../../doc/html/boost_asio/reference/Handler.html" target="_top"><span class="emphasis"><em>Handler</em></span></a><span class="special">,</span>
41 <span class="keyword">class</span> <a href="../../../../../../doc/html/boost_asio/reference/Executor1.html" target="_top"><span class="emphasis"><em>Executor1</em></span></a><span class="special">,</span>
42 <span class="keyword">class</span> <a href="https://en.cppreference.com/w/cpp/named_req/Allocator" target="_top"><span class="emphasis"><em>Allocator</em></span></a> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">void</span><span class="special">>></span>
43 <span class="keyword">class</span> <span class="identifier">async_base</span>
46 <a name="beast.ref.boost__beast__async_base.h1"></a>
47 <span class="phrase"><a name="beast.ref.boost__beast__async_base.types"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.types">Types</a>
49 <div class="informaltable"><table class="table">
70 <a class="link" href="boost__beast__async_base/allocator_type.html" title="async_base::allocator_type"><span class="bold"><strong>allocator_type</strong></span></a>
75 The type of allocator associated with this object.
82 <a class="link" href="boost__beast__async_base/executor_type.html" title="async_base::executor_type"><span class="bold"><strong>executor_type</strong></span></a>
87 The type of executor associated with this object.
94 <a name="beast.ref.boost__beast__async_base.h2"></a>
95 <span class="phrase"><a name="beast.ref.boost__beast__async_base.member_functions"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.member_functions">Member
98 <div class="informaltable"><table class="table">
119 <a class="link" href="boost__beast__async_base/async_base.html" title="async_base::async_base"><span class="bold"><strong>async_base</strong></span></a>
134 <a class="link" href="boost__beast__async_base/complete.html" title="async_base::complete"><span class="bold"><strong>complete</strong></span></a>
139 Invoke the final completion handler, maybe using post.
146 <a class="link" href="boost__beast__async_base/complete_now.html" title="async_base::complete_now"><span class="bold"><strong>complete_now</strong></span></a>
151 Invoke the final completion handler.
158 <a class="link" href="boost__beast__async_base/get_allocator.html" title="async_base::get_allocator"><span class="bold"><strong>get_allocator</strong></span></a>
163 Returns the allocator associated with this object.
170 <a class="link" href="boost__beast__async_base/get_executor.html" title="async_base::get_executor"><span class="bold"><strong>get_executor</strong></span></a>
175 Returns the executor associated with this object.
182 <a class="link" href="boost__beast__async_base/handler.html" title="async_base::handler"><span class="bold"><strong>handler</strong></span></a>
187 Returns the handler associated with this object.
194 <a class="link" href="boost__beast__async_base/operator_eq_.html" title="async_base::operator="><span class="bold"><strong>operator=</strong></span></a>
203 <a class="link" href="boost__beast__async_base/release_handler.html" title="async_base::release_handler"><span class="bold"><strong>release_handler</strong></span></a>
208 Returns ownership of the handler associated with this object.
215 <a class="link" href="boost__beast__async_base/async_base_dtor_.html" title="async_base::~async_base"><span class="bold"><strong>~async_base</strong></span></a>
224 <a name="beast.ref.boost__beast__async_base.h3"></a>
225 <span class="phrase"><a name="beast.ref.boost__beast__async_base.description"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.description">Description</a>
228 A function object submitted to intermediate initiating functions during a
229 composed operation may derive from this type to inherit all of the boilerplate
230 to forward the executor, allocator, and legacy customization points associated
231 with the completion handler invoked at the end of the composed operation.
232 The composed operation must be typical; that is, associated with one executor
233 of an I/O object, and invoking a caller-provided completion handler when
234 the operation is finished. Classes derived from <a class="link" href="boost__beast__async_base.html" title="async_base"><code class="computeroutput"><span class="identifier">async_base</span></code></a> will acquire these properties:
236 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
237 <li class="listitem">
238 Ownership of the final completion handler provided upon construction.
240 <li class="listitem">
241 If the final handler has an associated allocator, this allocator will
242 be propagated to the composed operation subclass. Otherwise, the associated
243 allocator will be the type specified in the allocator template parameter,
244 or the default of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">void</span><span class="special">></span></code> if the parameter is omitted.
246 <li class="listitem">
247 If the final handler has an associated executor, then it will be used
248 as the executor associated with the composed operation. Otherwise, the
249 specified <code class="computeroutput"><span class="identifier">Executor1</span></code> will
250 be the type of executor associated with the composed operation.
252 <li class="listitem">
253 An instance of <code class="computeroutput"><span class="identifier">net</span><span class="special">::</span><span class="identifier">executor_work_guard</span></code> for the instance
254 of <code class="computeroutput"><span class="identifier">Executor1</span></code> shall be
255 maintained until either the final handler is invoked, or the operation
256 base is destroyed, whichever comes first.
258 <li class="listitem">
259 Calls to the legacy customization points <code class="computeroutput"><span class="identifier">asio_handler_invoke</span></code>,
260 <code class="computeroutput"><span class="identifier">asio_handler_allocate</span></code>,
261 <code class="computeroutput"><span class="identifier">asio_handler_deallocate</span></code>,
262 and <code class="computeroutput"><span class="identifier">asio_handler_is_continuation</span></code>,
263 which use argument-dependent lookup, will be forwarded to the legacy
264 customization points associated with the handler.
268 <a name="beast.ref.boost__beast__async_base.h4"></a>
269 <span class="phrase"><a name="beast.ref.boost__beast__async_base.example"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.example">Example</a>
272 The following code demonstrates how <a class="link" href="boost__beast__async_base.html" title="async_base"><code class="computeroutput"><span class="identifier">async_base</span></code></a> may be be used to assist
273 authoring an asynchronous initiating function, by providing all of the boilerplate
274 to manage the final completion handler in a way that maintains the allocator
275 and executor associations:
277 <pre class="programlisting"><span class="comment">// Asynchronously read into a buffer until the buffer is full, or an error occurs</span>
278 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">AsyncReadStream</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">ReadHandler</span><span class="special">></span>
279 <span class="keyword">typename</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">async_result</span><span class="special"><</span><span class="identifier">ReadHandler</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)>::</span><span class="identifier">return_type</span>
280 <span class="identifier">async_read</span><span class="special">(</span><span class="identifier">AsyncReadStream</span><span class="special">&</span> <span class="identifier">stream</span><span class="special">,</span> <span class="identifier">net</span><span class="special">::</span><span class="identifier">mutable_buffer</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">ReadHandler</span><span class="special">&&</span> <span class="identifier">handler</span><span class="special">)</span>
281 <span class="special">{</span>
282 <span class="keyword">using</span> <span class="identifier">handler_type</span> <span class="special">=</span> <span class="identifier">BOOST_ASIO_HANDLER_TYPE</span><span class="special">(</span><span class="identifier">ReadHandler</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">));</span>
283 <span class="keyword">using</span> <span class="identifier">base_type</span> <span class="special">=</span> <span class="identifier">async_base</span><span class="special"><</span><span class="identifier">handler_type</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">AsyncReadStream</span><span class="special">::</span><span class="identifier">executor_type</span><span class="special">>;</span>
285 <span class="keyword">struct</span> <span class="identifier">op</span> <span class="special">:</span> <span class="identifier">base_type</span>
286 <span class="special">{</span>
287 <span class="identifier">AsyncReadStream</span><span class="special">&</span> <span class="identifier">stream_</span><span class="special">;</span>
288 <span class="identifier">net</span><span class="special">::</span><span class="identifier">mutable_buffer</span> <span class="identifier">buffer_</span><span class="special">;</span>
289 <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">total_bytes_transferred_</span><span class="special">;</span>
291 <span class="identifier">op</span><span class="special">(</span>
292 <span class="identifier">AsyncReadStream</span><span class="special">&</span> <span class="identifier">stream</span><span class="special">,</span>
293 <span class="identifier">net</span><span class="special">::</span><span class="identifier">mutable_buffer</span> <span class="identifier">buffer</span><span class="special">,</span>
294 <span class="identifier">handler_type</span><span class="special">&</span> <span class="identifier">handler</span><span class="special">)</span>
295 <span class="special">:</span> <span class="identifier">base_type</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(</span><span class="identifier">handler</span><span class="special">),</span> <span class="identifier">stream</span><span class="special">.</span><span class="identifier">get_executor</span><span class="special">())</span>
296 <span class="special">,</span> <span class="identifier">stream_</span><span class="special">(</span><span class="identifier">stream</span><span class="special">)</span>
297 <span class="special">,</span> <span class="identifier">buffer_</span><span class="special">(</span><span class="identifier">buffer</span><span class="special">)</span>
298 <span class="special">,</span> <span class="identifier">total_bytes_transferred_</span><span class="special">(</span><span class="number">0</span><span class="special">)</span>
299 <span class="special">{</span>
300 <span class="special">(*</span><span class="keyword">this</span><span class="special">)({},</span> <span class="number">0</span><span class="special">,</span> <span class="keyword">false</span><span class="special">);</span> <span class="comment">// start the operation</span>
301 <span class="special">}</span>
303 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()(</span><span class="identifier">error_code</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">bytes_transferred</span><span class="special">,</span> <span class="keyword">bool</span> <span class="identifier">is_continuation</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">)</span>
304 <span class="special">{</span>
305 <span class="comment">// Adjust the count of bytes and advance our buffer</span>
306 <span class="identifier">total_bytes_transferred_</span> <span class="special">+=</span> <span class="identifier">bytes_transferred</span><span class="special">;</span>
307 <span class="identifier">buffer_</span> <span class="special">=</span> <span class="identifier">buffer_</span> <span class="special">+</span> <span class="identifier">bytes_transferred</span><span class="special">;</span>
309 <span class="comment">// Keep reading until buffer is full or an error occurs</span>
310 <span class="keyword">if</span><span class="special">(!</span> <span class="identifier">ec</span> <span class="special">&&</span> <span class="identifier">buffer_</span><span class="special">.</span><span class="identifier">size</span><span class="special">()</span> <span class="special">></span> <span class="number">0</span><span class="special">)</span>
311 <span class="keyword">return</span> <span class="identifier">stream_</span><span class="special">.</span><span class="identifier">async_read_some</span><span class="special">(</span><span class="identifier">buffer_</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">move</span><span class="special">(*</span><span class="keyword">this</span><span class="special">));</span>
313 <span class="comment">// Call the completion handler with the result. If `is_continuation` is</span>
314 <span class="comment">// false, which happens on the first time through this function, then</span>
315 <span class="comment">// `net::post` will be used to call the completion handler, otherwise</span>
316 <span class="comment">// the completion handler will be invoked directly.</span>
318 <span class="keyword">this</span><span class="special">-></span><span class="identifier">complete</span><span class="special">(</span><span class="identifier">is_continuation</span><span class="special">,</span> <span class="identifier">ec</span><span class="special">,</span> <span class="identifier">total_bytes_transferred_</span><span class="special">);</span>
319 <span class="special">}</span>
320 <span class="special">};</span>
322 <span class="identifier">net</span><span class="special">::</span><span class="identifier">async_completion</span><span class="special"><</span><span class="identifier">ReadHandler</span><span class="special">,</span> <span class="keyword">void</span><span class="special">(</span><span class="identifier">error_code</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)></span> <span class="identifier">init</span><span class="special">{</span><span class="identifier">handler</span><span class="special">};</span>
323 <span class="identifier">op</span><span class="special">(</span><span class="identifier">stream</span><span class="special">,</span> <span class="identifier">buffer</span><span class="special">,</span> <span class="identifier">init</span><span class="special">.</span><span class="identifier">completion_handler</span><span class="special">);</span>
324 <span class="keyword">return</span> <span class="identifier">init</span><span class="special">.</span><span class="identifier">result</span><span class="special">.</span><span class="identifier">get</span><span class="special">();</span>
325 <span class="special">}</span>
328 Data members of composed operations implemented as completion handlers do
329 not have stable addresses, as the composed operation object is move constructed
330 upon each call to an initiating function. For most operations this is not
331 a problem. For complex operations requiring stable temporary storage, the
332 class <a class="link" href="boost__beast__stable_async_base.html" title="stable_async_base"><code class="computeroutput"><span class="identifier">stable_async_base</span></code></a> is provided which
333 offers additional functionality:
335 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
336 <li class="listitem">
337 The free function <a class="link" href="boost__beast__allocate_stable.html" title="allocate_stable"><code class="computeroutput"><span class="identifier">allocate_stable</span></code></a> may be used
338 to allocate one or more temporary objects associated with the composed
341 <li class="listitem">
342 Memory for stable temporary objects is allocated using the allocator
343 associated with the composed operation.
345 <li class="listitem">
346 Stable temporary objects are automatically destroyed, and the memory
347 freed using the associated allocator, either before the final completion
348 handler is invoked (a Networking requirement) or when the composed operation
349 is destroyed, whichever occurs first.
353 <a name="beast.ref.boost__beast__async_base.h5"></a>
354 <span class="phrase"><a name="beast.ref.boost__beast__async_base.temporary_storage_example"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.temporary_storage_example">Temporary
358 The following example demonstrates how a composed operation may store a temporary
362 <a name="beast.ref.boost__beast__async_base.h6"></a>
363 <span class="phrase"><a name="beast.ref.boost__beast__async_base.template_parameters"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.template_parameters">Template
366 <div class="informaltable"><table class="table">
387 <code class="computeroutput"><span class="identifier">Handler</span></code>
392 The type of the completion handler to store. This type must meet
393 the requirements of <span class="emphasis"><em>CompletionHandler</em></span>.
400 <code class="computeroutput"><span class="identifier">Executor1</span></code>
405 The type of the executor used when the handler has no associated
406 executor. An instance of this type must be provided upon construction.
407 The implementation will maintain an executor work guard and a copy
415 <code class="computeroutput"><span class="identifier">Allocator</span></code>
420 The allocator type to use if the handler does not have an associated
421 allocator. If this parameter is omitted, then <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">void</span><span class="special">></span></code> will be used. If the specified
422 allocator is not default constructible, an instance of the type
423 must be provided upon construction.
430 <a name="beast.ref.boost__beast__async_base.h7"></a>
431 <span class="phrase"><a name="beast.ref.boost__beast__async_base.see_also"></a></span><a class="link" href="boost__beast__async_base.html#beast.ref.boost__beast__async_base.see_also">See
435 <a class="link" href="boost__beast__stable_async_base.html" title="stable_async_base"><code class="computeroutput"><span class="identifier">stable_async_base</span></code></a>
438 Convenience header <code class="literal"><<a href="../../../../../../boost/beast/core.hpp" target="_top">boost/beast/core.hpp</a>></code>
441 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
442 <td align="left"></td>
443 <td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie
445 Distributed under the Boost Software License, Version 1.0. (See accompanying
446 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>)
451 <div class="spirit-nav">
452 <a accesskey="p" href="boost__beast__allocate_stable.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="boost__beast__async_base/allocator_type.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>