1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Custom Memory Allocation</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="line_based.html" title="Line-Based Operations"> 10<link rel="next" href="handler_tracking.html" title="Handler Tracking"> 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="line_based.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="handler_tracking.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.allocation"></a><a class="link" href="allocation.html" title="Custom Memory Allocation">Custom Memory 28 Allocation</a> 29</h4></div></div></div> 30<p> 31 Many asynchronous operations need to allocate an object to store state 32 associated with the operation. For example, a Win32 implementation needs 33 <code class="computeroutput"><span class="identifier">OVERLAPPED</span></code>-derived objects 34 to pass to Win32 API functions. 35 </p> 36<p> 37 Furthermore, programs typically contain easily identifiable chains of asynchronous 38 operations. A half duplex protocol implementation (e.g. an HTTP server) 39 would have a single chain of operations per client (receives followed by 40 sends). A full duplex protocol implementation would have two chains executing 41 in parallel. Programs should be able to leverage this knowledge to reuse 42 memory for all asynchronous operations in a chain. 43 </p> 44<p> 45 Given a copy of a user-defined <code class="computeroutput"><span class="identifier">Handler</span></code> 46 object <code class="computeroutput"><span class="identifier">h</span></code>, if the implementation 47 needs to allocate memory associated with that handler it will obtain an 48 allocator using the <code class="computeroutput"><span class="identifier">get_associated_allocator</span></code> 49 function. For example: 50 </p> 51<pre class="programlisting"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">associated_allocator_t</span><span class="special"><</span><span class="identifier">Handler</span><span class="special">></span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">asio</span><span class="special">::</span><span class="identifier">get_associated_allocator</span><span class="special">(</span><span class="identifier">h</span><span class="special">);</span> 52</pre> 53<p> 54 The associated allocator must satisfy the standard Allocator requirements. 55 </p> 56<p> 57 By default, handlers use the standard allocator (which is implemented in 58 terms of <code class="computeroutput"><span class="special">::</span><span class="keyword">operator</span> 59 <span class="keyword">new</span><span class="special">()</span></code> 60 and <code class="computeroutput"><span class="special">::</span><span class="keyword">operator</span> 61 <span class="keyword">delete</span><span class="special">()</span></code>). 62 The allocator may be customised for a particular handler type by specifying 63 a nested type <code class="computeroutput"><span class="identifier">allocator_type</span></code> 64 and member function <code class="computeroutput"><span class="identifier">get_allocator</span><span class="special">()</span></code>: 65 </p> 66<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">my_handler</span> 67<span class="special">{</span> 68<span class="keyword">public</span><span class="special">:</span> 69 <span class="comment">// Custom implementation of Allocator type requirements.</span> 70 <span class="keyword">typedef</span> <span class="identifier">my_allocator</span> <span class="identifier">allocator_type</span><span class="special">;</span> 71 72 <span class="comment">// Return a custom allocator implementation.</span> 73 <span class="identifier">allocator_type</span> <span class="identifier">get_allocator</span><span class="special">()</span> <span class="keyword">const</span> <span class="keyword">noexcept</span> 74 <span class="special">{</span> 75 <span class="keyword">return</span> <span class="identifier">my_allocator</span><span class="special">();</span> 76 <span class="special">}</span> 77 78 <span class="keyword">void</span> <span class="keyword">operator</span><span class="special">()()</span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> 79<span class="special">};</span> 80</pre> 81<p> 82 In more complex cases, the <code class="computeroutput"><span class="identifier">associated_allocator</span></code> 83 template may be partially specialised directly: 84 </p> 85<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">asio</span> <span class="special">{</span> 86 87 <span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Allocator</span><span class="special">></span> 88 <span class="keyword">struct</span> <span class="identifier">associated_allocator</span><span class="special"><</span><span class="identifier">my_handler</span><span class="special">,</span> <span class="identifier">Allocator</span><span class="special">></span> 89 <span class="special">{</span> 90 <span class="comment">// Custom implementation of Allocator type requirements.</span> 91 <span class="keyword">typedef</span> <span class="identifier">my_allocator</span> <span class="identifier">type</span><span class="special">;</span> 92 93 <span class="comment">// Return a custom allocator implementation.</span> 94 <span class="keyword">static</span> <span class="identifier">type</span> <span class="identifier">get</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">my_handler</span><span class="special">&,</span> 95 <span class="keyword">const</span> <span class="identifier">Allocator</span><span class="special">&</span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">Allocator</span><span class="special">())</span> <span class="keyword">noexcept</span> 96 <span class="special">{</span> 97 <span class="keyword">return</span> <span class="identifier">my_allocator</span><span class="special">();</span> 98 <span class="special">}</span> 99 <span class="special">};</span> 100 101<span class="special">}</span> <span class="special">}</span> <span class="comment">// namespace boost::asio</span> 102</pre> 103<p> 104 The implementation guarantees that the deallocation will occur before the 105 associated handler is invoked, which means the memory is ready to be reused 106 for any new asynchronous operations started by the handler. 107 </p> 108<p> 109 The custom memory allocation functions may be called from any user-created 110 thread that is calling a library function. The implementation guarantees 111 that, for the asynchronous operations included the library, the implementation 112 will not make concurrent calls to the memory allocation functions for that 113 handler. The implementation will insert appropriate memory barriers to 114 ensure correct memory visibility should allocation functions need to be 115 called from different threads. 116 </p> 117<h6> 118<a name="boost_asio.overview.core.allocation.h0"></a> 119 <span class="phrase"><a name="boost_asio.overview.core.allocation.see_also"></a></span><a class="link" href="allocation.html#boost_asio.overview.core.allocation.see_also">See 120 Also</a> 121 </h6> 122<p> 123 <a class="link" href="../../reference/associated_allocator.html" title="associated_allocator">associated_allocator</a>, 124 <a class="link" href="../../reference/get_associated_allocator.html" title="get_associated_allocator">get_associated_allocator</a>, 125 <a class="link" href="../../examples/cpp03_examples.html#boost_asio.examples.cpp03_examples.allocation">custom memory 126 allocation example (C++03)</a>, <a class="link" href="../../examples/cpp11_examples.html#boost_asio.examples.cpp11_examples.allocation">custom 127 memory allocation example (C++11)</a>. 128 </p> 129</div> 130<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 131<td align="left"></td> 132<td align="right"><div class="copyright-footer">Copyright © 2003-2020 Christopher M. 133 Kohlhoff<p> 134 Distributed under the Boost Software License, Version 1.0. (See accompanying 135 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>) 136 </p> 137</div></td> 138</tr></table> 139<hr> 140<div class="spirit-nav"> 141<a accesskey="p" href="line_based.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="handler_tracking.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 142</div> 143</body> 144</html> 145
