memory
/
md_doc_writing_allocators.html

<!-- HTML header for doxygen 1.8.16-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.18"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>memory: Writing own RawAllocator classes</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">memory
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<div id="main-nav">
    <ul class="sm sm-dox" id="main-menu">
        <li><a href="index.html">Main Page</a></li>
        <li><a href="md_doc_tutorial.html">Tutorial</a></li>
        <li><a href="namespacefoonathan_1_1memory.html">Index</a></li>
        <li><a href="files.html">Files</a></li>
    </ul>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.18 -->
</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">Writing own RawAllocator classes </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>There are, in general, three different ways and one special case to write a <a href="md_doc_concepts.html#concept_rawallocator">RawAllocator</a> class. See the link for the exact requirements and behavior for each function.</p>
<h1><a class="anchor" id="autotoc_md74"></a>
0. Write a normal Allocator class</h1>
<p>Just go ahead and write a normal <code>Allocator</code> class. It will work just fine and can be used anywhere a <a href="md_doc_concepts.html#concept_rawallocator">RawAllocator</a> is required. Keep in mind, though, that the <code>construct</code> or <code>destroy</code> functions will not be called and its pointer typedefs not used.</p>
<h1><a class="anchor" id="autotoc_md75"></a>
1. Fulfill the requirements for the default allocator_traits</h1>
<p>This is the easiest way. The default specialization of <a class="el" href="classfoonathan_1_1memory_1_1allocator__traits.html">allocator_traits</a> will forward to member functions, if they exist, and has some fallback, if they don't. The following class overrides all the fallbacks:</p>
<div class="fragment"><div class="line"><span class="keyword">struct </span>raw_allocator</div>
<div class="line">{</div>
<div class="line">    <span class="keyword">using</span> is_stateful = std::integral_constant&lt;bool, Value&gt;;</div>
<div class="line"> </div>
<div class="line">    <span class="keywordtype">void</span>* allocate_node(std::size_t size, std::size_t alignment);</div>
<div class="line">    <span class="keywordtype">void</span> deallocate_node(<span class="keywordtype">void</span> *node, std::size_t size, std::size_t alignment) noexcept;</div>
<div class="line"> </div>
<div class="line">    <span class="keywordtype">void</span>* allocate_array(std::size_t count, std::size_t size, std::size_t alignment);</div>
<div class="line">    <span class="keywordtype">void</span> deallocate_array(<span class="keywordtype">void</span> *ptr, std::size_t count, std::size_t size, std::size_t alignment) noexcept;</div>
<div class="line"> </div>
<div class="line">    std::size_t max_node_size() <span class="keyword">const</span>;</div>
<div class="line">    std::size_t max_array_size() <span class="keyword">const</span>;</div>
<div class="line">    std::size_t max_alignment() <span class="keyword">const</span>;</div>
<div class="line">};</div>
</div><!-- fragment --><p>There are fallbacks for every function except <code>allocate_node()</code> and <code>deallocate_node()</code>. A minimum class thus only needs to provide those two functions. The fallbacks "do the right thing", for example <code>allocate_array()</code> forwards to <code>allocate_node()</code>, <code>is_stateful</code> is determined via <code>std::is_empty</code> and <code>max_node_size()</code> returns the maximum possible value.</p>
<p>Keep in mind that a <a href="md_doc_concepts.html#concept_rawallocator">RawAllocator</a> has to be nothrow moveable and be valid to be used as a non-polymorphic base class, i.e. as a <code>private</code> base to use EBO.</p>
<p>The full interface is provided by the <a class="el" href="classfoonathan_1_1memory_1_1allocator__storage.html">allocator_storage</a> typedefs. Other classes where this approach is used are <a class="el" href="group__allocator.html#ga22bca7a15392be2aa9be773d838ec4f4">heap_allocator</a> or <a class="el" href="classfoonathan_1_1memory_1_1aligned__allocator.html">aligned_allocator</a>. The latter also provides the full interface.</p>
<h1><a class="anchor" id="autotoc_md76"></a>
2. Specialize the allocator_traits</h1>
<p>But sometimes it is not attractive to provide the full interface. An example is the library class <a class="el" href="classfoonathan_1_1memory_1_1memory__stack.html">memory_stack</a>. Its interface consists of typical behaviors required for a stack, like unwinding, and it does not make sense to provide a <code>deallocate_node()</code> function for it since there is no direct way to do so - only via unwinding.</p>
<p>In this case, the <a class="el" href="classfoonathan_1_1memory_1_1allocator__traits.html">allocator_traits</a> can be specialized for your type. Keep in mind that it is in the sub-namespace <code>memory</code> of the namespace <code>foonathan</code>. It needs to provide the following interface:</p>
<div class="fragment"><div class="line"><span class="keyword">template</span> &lt;&gt;</div>
<div class="line"><span class="keyword">class </span>allocator_traits&lt;raw_allocator&gt;</div>
<div class="line">{</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line">    <span class="keyword">using</span> allocator_type = raw_allocator;</div>
<div class="line">    <span class="keyword">using</span> is_stateful = std::integral_constant&lt;bool, Value&gt;;</div>
<div class="line"> </div>
<div class="line">    <span class="keyword">static</span> <span class="keywordtype">void</span>* allocate_node(allocator_type &amp;state, std::size_t size, std::size_t alignment);</div>
<div class="line">    <span class="keyword">static</span> <span class="keywordtype">void</span> deallocate_node(allocator_type &amp;state, <span class="keywordtype">void</span> *node, std::size_t size, std::size_t alignment) noexcept;</div>
<div class="line"> </div>
<div class="line">    <span class="keyword">static</span> <span class="keywordtype">void</span>* allocate_array(allocator_type &amp;state, std::size_t count, std::size_t size, std::size_t alignment);</div>
<div class="line">    <span class="keyword">static</span> <span class="keywordtype">void</span> deallocate_array(allocator_type &amp;state, <span class="keywordtype">void</span> *array, std::size_t count, std::size_t size, std::size_t alignment) noexcept;</div>
<div class="line"> </div>
<div class="line">    <span class="keyword">static</span> std::size_t max_node_size(<span class="keyword">const</span> allocator_type &amp;state);</div>
<div class="line">    <span class="keyword">static</span> std::size_t max_array_size(<span class="keyword">const</span> allocator_type &amp;state);</div>
<div class="line">    <span class="keyword">static</span> std::size_t max_alignment(<span class="keyword">const</span> allocator_type &amp;state);</div>
<div class="line">};</div>
</div><!-- fragment --><p>This approach is used in the mentioned <a class="el" href="classfoonathan_1_1memory_1_1memory__stack.html">memory_stack</a> but also the <a class="el" href="classfoonathan_1_1memory_1_1memory__pool.html">memory_pool</a> classes.</p>
<h1><a class="anchor" id="autotoc_md77"></a>
3. Forward all behavior to another class</h1>
<p>The <a class="el" href="classfoonathan_1_1memory_1_1allocator__traits.html">allocator_traits</a> provide a typedef <code>allocator_type</code>. This type is the actual type used for the (de-)allocation and will be stored in all classes taking a <a href="md_doc_concepts.html#concept_rawallocator">RawAllocator</a>. Its only requirement is that it is implicitly constructible from the actual type instantiated and that it is a <a href="md_doc_concepts.html#concept_rawallocator">RawAllocator</a>.</p>
<p>The main use for this typedef is to support <code>Allocator</code> classes. They need to be rebound to <code>char</code> to allow byte-size allocations prior before they are actually used.</p>
<p>Using this technique otherwise is rather esoteric and I do not see any reason for it, but it is possible. Let there be a class <code>raw_allocator</code> that is a <a href="md_doc_concepts.html#concept_rawallocator">RawAllocator</a>, i.e. it provides the appropriate traits interface using any of the mentioned ways. This class also provides a constructor taking the class <code>my_allocator</code> that wants to forward to it. Then you only need to write:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>my_allocator {...};</div>
<div class="line"> </div>
<div class="line"><span class="keyword">class </span>raw_allocator</div>
<div class="line">{</div>
<div class="line"><span class="keyword">public</span>:</div>
<div class="line">    raw_allocator(my_allocator &amp;)</div>
<div class="line">    {</div>
<div class="line">        ...</div>
<div class="line">    }</div>
<div class="line"> </div>
<div class="line">    <span class="comment">// provides the required interface or has a traits specialization</span></div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line">...</div>
<div class="line">template &lt;&gt;</div>
<div class="line"><span class="keyword">class </span>allocator_traits&lt;my_allocator&gt;</div>
<div class="line">: <span class="keyword">public</span> allocator_traits&lt;raw_allocator&gt;</div>
<div class="line">{};</div>
</div><!-- fragment --> </div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- HTML footer for doxygen 1.8.16-->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.18
</small></address>
</body>
</html>