doc/html/interprocess/architecture.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   5 <title>Architecture and internals</title>
   6 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   7 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   8 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   9 <link rel="up" href="../interprocess.html" title="Chapter&#160;18.&#160;Boost.Interprocess">
  10 <link rel="prev" href="interprocess_smart_ptr.html" title="Ownership smart pointers">
  11 <link rel="next" href="customizing_interprocess.html" title="Customizing Boost.Interprocess">
  12 </head>
  13 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  14 <table cellpadding="2" width="100%"><tr>
  15 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
  16 <td align="center"><a href="../../../index.html">Home</a></td>
  17 <td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  19 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  20 <td align="center"><a href="../../../more/index.htm">More</a></td>
  21 </tr></table>
  22 <hr>
  23 <div class="spirit-nav">
  24 <a accesskey="p" href="interprocess_smart_ptr.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../interprocess.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="customizing_interprocess.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  25 </div>
  26 <div class="section">
  27 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  28 <a name="interprocess.architecture"></a><a class="link" href="architecture.html" title="Architecture and internals">Architecture and internals</a>
  29 </h2></div></div></div>
  30 <div class="toc"><dl class="toc">
  31 <dt><span class="section"><a href="architecture.html#interprocess.architecture.basic_guidelines">Basic guidelines</a></span></dt>
  32 <dt><span class="section"><a href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed">From
  33       the memory algorithm to the managed segment</a></span></dt>
  34 <dt><span class="section"><a href="architecture.html#interprocess.architecture.allocators_containers">Allocators
  35       and containers</a></span></dt>
  36 <dt><span class="section"><a href="architecture.html#interprocess.architecture.performance">Performance of
  37       Boost.Interprocess</a></span></dt>
  38 </dl></div>
  39 <div class="section">
  40 <div class="titlepage"><div><div><h3 class="title">
  41 <a name="interprocess.architecture.basic_guidelines"></a><a class="link" href="architecture.html#interprocess.architecture.basic_guidelines" title="Basic guidelines">Basic guidelines</a>
  42 </h3></div></div></div>
  43 <p>
  44         When building <span class="bold"><strong>Boost.Interprocess</strong></span> architecture,
  45         I took some basic guidelines that can be summarized by these points:
  46       </p>
  47 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  48 <li class="listitem">
  49             <span class="bold"><strong>Boost.Interprocess</strong></span> should be portable
  50             at least in UNIX and Windows systems. That means unifying not only interfaces
  51             but also behaviour. This is why <span class="bold"><strong>Boost.Interprocess</strong></span>
  52             has chosen kernel or filesystem persistence for shared memory and named
  53             synchronization mechanisms. Process persistence for shared memory is
  54             also desirable but it's difficult to achieve in UNIX systems.
  55           </li>
  56 <li class="listitem">
  57             <span class="bold"><strong>Boost.Interprocess</strong></span> inter-process synchronization
  58             primitives should be equal to thread synchronization primitives. <span class="bold"><strong>Boost.Interprocess</strong></span> aims to have an interface compatible
  59             with the C++ standard thread API.
  60           </li>
  61 <li class="listitem">
  62             <span class="bold"><strong>Boost.Interprocess</strong></span> architecture should
  63             be modular, customizable but efficient. That's why <span class="bold"><strong>Boost.Interprocess</strong></span>
  64             is based on templates and memory algorithms, index types, mutex types
  65             and other classes are templatizable.
  66           </li>
  67 <li class="listitem">
  68             <span class="bold"><strong>Boost.Interprocess</strong></span> architecture should
  69             allow the same concurrency as thread based programming. Different mutual
  70             exclusion levels are defined so that a process can concurrently allocate
  71             raw memory when expanding a shared memory vector while another process
  72             can be safely searching a named object.
  73           </li>
  74 <li class="listitem">
  75             <span class="bold"><strong>Boost.Interprocess</strong></span> containers know nothing
  76             about <span class="bold"><strong>Boost.Interprocess</strong></span>. All specific
  77             behaviour is contained in the STL-like allocators. That allows STL vendors
  78             to slightly modify (or better said, generalize) their standard container
  79             implementations and obtain a fully std::allocator and boost::interprocess::allocator
  80             compatible container. This also make <span class="bold"><strong>Boost.Interprocess</strong></span>
  81             containers compatible with standard algorithms.
  82           </li>
  83 </ul></div>
  84 <p>
  85         <span class="bold"><strong>Boost.Interprocess</strong></span> is built above 3 basic
  86         classes: a <span class="bold"><strong>memory algorithm</strong></span>, a <span class="bold"><strong>segment manager</strong></span> and a <span class="bold"><strong>managed
  87         memory segment</strong></span>:
  88       </p>
  89 </div>
  90 <div class="section">
  91 <div class="titlepage"><div><div><h3 class="title">
  92 <a name="interprocess.architecture.architecture_algorithm_to_managed"></a><a class="link" href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed" title="From the memory algorithm to the managed segment">From
  93       the memory algorithm to the managed segment</a>
  94 </h3></div></div></div>
  95 <div class="toc"><dl class="toc">
  96 <dt><span class="section"><a href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed.architecture_memory_algorithm">The
  97         memory algorithm</a></span></dt>
  98 <dt><span class="section"><a href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed.architecture_segment_manager">The
  99         segment manager</a></span></dt>
 100 <dt><span class="section"><a href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed.architecture_managed_memory">Boost.Interprocess
 101         managed memory segments</a></span></dt>
 102 </dl></div>
 103 <div class="section">
 104 <div class="titlepage"><div><div><h4 class="title">
 105 <a name="interprocess.architecture.architecture_algorithm_to_managed.architecture_memory_algorithm"></a><a class="link" href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed.architecture_memory_algorithm" title="The memory algorithm">The
 106         memory algorithm</a>
 107 </h4></div></div></div>
 108 <p>
 109           The <span class="bold"><strong>memory algorithm</strong></span> is an object that
 110           is placed in the first bytes of a shared memory/memory mapped file segment.
 111           The <span class="bold"><strong>memory algorithm</strong></span> can return portions
 112           of that segment to users marking them as used and the user can return those
 113           portions to the <span class="bold"><strong>memory algorithm</strong></span> so that
 114           the <span class="bold"><strong>memory algorithm</strong></span> mark them as free
 115           again. There is an exception though: some bytes beyond the end of the memory
 116           algorithm object, are reserved and can't be used for this dynamic allocation.
 117           This "reserved" zone will be used to place other additional objects
 118           in a well-known place.
 119         </p>
 120 <p>
 121           To sum up, a <span class="bold"><strong>memory algorithm</strong></span> has the
 122           same mission as malloc/free of standard C library, but it just can return
 123           portions of the segment where it is placed. The layout of a memory segment
 124           would be:
 125         </p>
 126 <pre class="programlisting"><span class="identifier">Layout</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">memory</span> <span class="identifier">segment</span><span class="special">:</span>
 127  <span class="identifier">____________</span> <span class="identifier">__________</span> <span class="identifier">____________________________________________</span>
 128 <span class="special">|</span>            <span class="special">|</span>          <span class="special">|</span>                                            <span class="special">|</span>
 129 <span class="special">|</span>   <span class="identifier">memory</span>   <span class="special">|</span> <span class="identifier">reserved</span> <span class="special">|</span>  <span class="identifier">The</span> <span class="identifier">memory</span> <span class="identifier">algorithm</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">portions</span> <span class="special">|</span>
 130 <span class="special">|</span> <span class="identifier">algorithm</span>  <span class="special">|</span>          <span class="special">|</span>  <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">rest</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">segment</span><span class="special">.</span>               <span class="special">|</span>
 131 <span class="special">|</span><span class="identifier">____________</span><span class="special">|</span><span class="identifier">__________</span><span class="special">|</span><span class="identifier">____________________________________________</span><span class="special">|</span>
 132 </pre>
 133 <p>
 134           The <span class="bold"><strong>memory algorithm</strong></span> takes care of memory
 135           synchronizations, just like malloc/free guarantees that two threads can
 136           call malloc/free at the same time. This is usually achieved placing a process-shared
 137           mutex as a member of the memory algorithm. Take in care that the memory
 138           algorithm knows <span class="bold"><strong>nothing</strong></span> about the segment
 139           (if it is shared memory, a shared memory file, etc.). For the memory algorithm
 140           the segment is just a fixed size memory buffer.
 141         </p>
 142 <p>
 143           The <span class="bold"><strong>memory algorithm</strong></span> is also a configuration
 144           point for the rest of the <span class="bold"><strong>Boost.Interprocess</strong></span>
 145           framework since it defines two basic types as member typedefs:
 146         </p>
 147 <pre class="programlisting"><span class="keyword">typedef</span> <span class="comment">/*implementation dependent*/</span> <span class="identifier">void_pointer</span><span class="special">;</span>
 148 <span class="keyword">typedef</span> <span class="comment">/*implementation dependent*/</span> <span class="identifier">mutex_family</span><span class="special">;</span>
 149 </pre>
 150 <p>
 151           The <code class="computeroutput"><span class="identifier">void_pointer</span></code> typedef
 152           defines the pointer type that will be used in the <span class="bold"><strong>Boost.Interprocess</strong></span>
 153           framework (segment manager, allocators, containers). If the memory algorithm
 154           is ready to be placed in a shared memory/mapped file mapped in different
 155           base addresses, this pointer type will be defined as <code class="computeroutput"><span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span></code> or a similar relative pointer. If the
 156           <span class="bold"><strong>memory algorithm</strong></span> will be used just with
 157           fixed address mapping, <code class="computeroutput"><span class="identifier">void_pointer</span></code>
 158           can be defined as <code class="computeroutput"><span class="keyword">void</span><span class="special">*</span></code>.
 159         </p>
 160 <p>
 161           The rest of the interface of a <span class="bold"><strong>Boost.Interprocess</strong></span>
 162           <span class="bold"><strong>memory algorithm</strong></span> is described in <a class="link" href="customizing_interprocess.html#interprocess.customizing_interprocess.custom_interprocess_alloc" title="Writing a new shared memory allocation algorithm">Writing
 163           a new shared memory allocation algorithm</a> section. As memory algorithm
 164           examples, you can see the implementations <code class="computeroutput"><a class="link" href="../boost/interprocess/simple_seq_fit.html" title="Class template simple_seq_fit">simple_seq_fit</a></code>
 165           or <code class="computeroutput"><a class="link" href="../boost/interprocess/rbtree_best_fit.html" title="Class template rbtree_best_fit">rbtree_best_fit</a></code>
 166           classes.
 167         </p>
 168 </div>
 169 <div class="section">
 170 <div class="titlepage"><div><div><h4 class="title">
 171 <a name="interprocess.architecture.architecture_algorithm_to_managed.architecture_segment_manager"></a><a class="link" href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed.architecture_segment_manager" title="The segment manager">The
 172         segment manager</a>
 173 </h4></div></div></div>
 174 <p>
 175           The <span class="bold"><strong>segment manager</strong></span>, is an object also
 176           placed in the first bytes of the managed memory segment (shared memory,
 177           memory mapped file), that offers more sophisticated services built above
 178           the <span class="bold"><strong>memory algorithm</strong></span>. How can <span class="bold"><strong>both</strong></span> the segment manager and memory algorithm be
 179           placed in the beginning of the segment? That's because the segment manager
 180           <span class="bold"><strong>owns</strong></span> the memory algorithm: The truth is
 181           that the memory algorithm is <span class="bold"><strong>embedded</strong></span>
 182           in the segment manager:
 183         </p>
 184 <pre class="programlisting"><span class="identifier">The</span> <span class="identifier">layout</span> <span class="identifier">of</span> <span class="identifier">managed</span> <span class="identifier">memory</span> <span class="identifier">segment</span><span class="special">:</span>
 185  <span class="identifier">_______</span> <span class="identifier">_________________</span>
 186 <span class="special">|</span>       <span class="special">|</span>         <span class="special">|</span>       <span class="special">|</span>
 187 <span class="special">|</span> <span class="identifier">some</span>  <span class="special">|</span> <span class="identifier">memory</span>  <span class="special">|</span> <span class="identifier">other</span> <span class="special">|&lt;-</span> <span class="identifier">The</span> <span class="identifier">memory</span> <span class="identifier">algorithm</span> <span class="identifier">considers</span>
 188 <span class="special">|</span><span class="identifier">members</span><span class="special">|</span><span class="identifier">algorithm</span><span class="special">|</span><span class="identifier">members</span><span class="special">|</span>   <span class="string">"other members"</span> <span class="identifier">as</span> <span class="identifier">reserved</span> <span class="identifier">memory</span><span class="special">,</span> <span class="identifier">so</span>
 189 <span class="special">|</span><span class="identifier">_______</span><span class="special">|</span><span class="identifier">_________</span><span class="special">|</span><span class="identifier">_______</span><span class="special">|</span>   <span class="identifier">it</span> <span class="identifier">does</span> <span class="keyword">not</span> <span class="identifier">use</span> <span class="identifier">it</span> <span class="keyword">for</span> <span class="identifier">dynamic</span> <span class="identifier">allocation</span><span class="special">.</span>
 190 <span class="special">|</span><span class="identifier">_________________________</span><span class="special">|</span><span class="identifier">____________________________________________</span>
 191 <span class="special">|</span>                         <span class="special">|</span>                                            <span class="special">|</span>
 192 <span class="special">|</span>    <span class="identifier">segment</span> <span class="identifier">manager</span>      <span class="special">|</span>  <span class="identifier">The</span> <span class="identifier">memory</span> <span class="identifier">algorithm</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">portions</span> <span class="special">|</span>
 193 <span class="special">|</span>                         <span class="special">|</span>  <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">rest</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">segment</span><span class="special">.</span>               <span class="special">|</span>
 194 <span class="special">|</span><span class="identifier">_________________________</span><span class="special">|</span><span class="identifier">____________________________________________</span><span class="special">|</span>
 195 </pre>
 196 <p>
 197           The <span class="bold"><strong>segment manager</strong></span> initializes the memory
 198           algorithm and tells the memory manager that it should not use the memory
 199           where the rest of the <span class="bold"><strong>segment manager</strong></span>'s
 200           member are placed for dynamic allocations. The other members of the <span class="bold"><strong>segment manager</strong></span> are <span class="bold"><strong>a recursive
 201           mutex</strong></span> (defined by the memory algorithm's <span class="bold"><strong>mutex_family::recursive_mutex</strong></span>
 202           typedef member), and <span class="bold"><strong>two indexes (maps)</strong></span>:
 203           one to implement named allocations, and another one to implement "unique
 204           instance" allocations.
 205         </p>
 206 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 207 <li class="listitem">
 208               The first index is a map with a pointer to a c-string (the name of
 209               the named object) as a key and a structure with information of the
 210               dynamically allocated object (the most important being the address
 211               and the size of the object).
 212             </li>
 213 <li class="listitem">
 214               The second index is used to implement "unique instances"
 215               and is basically the same as the first index, but the name of the object
 216               comes from a <code class="computeroutput"><span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()</span></code>
 217               operation.
 218             </li>
 219 </ul></div>
 220 <p>
 221           The memory needed to store [name pointer, object information] pairs in
 222           the index is allocated also via the <span class="bold"><strong>memory algorithm</strong></span>,
 223           so we can tell that internal indexes are just like ordinary user objects
 224           built in the segment. The rest of the memory to store the name of the object,
 225           the object itself, and meta-data for destruction/deallocation is allocated
 226           using the <span class="bold"><strong>memory algorithm</strong></span> in a single
 227           <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code>
 228           call.
 229         </p>
 230 <p>
 231           As seen, the <span class="bold"><strong>segment manager</strong></span> knows <span class="bold"><strong>nothing</strong></span> about shared memory/memory mapped files.
 232           The <span class="bold"><strong>segment manager</strong></span> itself does not allocate
 233           portions of the segment, it just asks the <span class="bold"><strong>memory
 234           algorithm</strong></span> to allocate the needed memory from the rest of the
 235           segment. The <span class="bold"><strong>segment manager</strong></span> is a class
 236           built above the memory algorithm that offers named object construction,
 237           unique instance constructions, and many other services.
 238         </p>
 239 <p>
 240           The <span class="bold"><strong>segment manager</strong></span> is implemented in
 241           <span class="bold"><strong>Boost.Interprocess</strong></span> by the <code class="computeroutput"><a class="link" href="../boost/interprocess/segment_manager.html" title="Class template segment_manager">segment_manager</a></code>
 242           class.
 243         </p>
 244 <pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">CharType</span>
 245         <span class="special">,</span><span class="keyword">class</span> <span class="identifier">MemoryAlgorithm</span>
 246         <span class="special">,</span><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">IndexConfig</span><span class="special">&gt;</span> <span class="keyword">class</span> <span class="identifier">IndexType</span><span class="special">&gt;</span>
 247 <span class="keyword">class</span> <span class="identifier">segment_manager</span><span class="special">;</span>
 248 </pre>
 249 <p>
 250           As seen, the segment manager is quite generic: we can specify the character
 251           type to be used to identify named objects, we can specify the memory algorithm
 252           that will control dynamically the portions of the memory segment, and we
 253           can specify also the index type that will store the [name pointer, object
 254           information] mapping. We can construct our own index types as explained
 255           in <a class="link" href="customizing_interprocess.html#interprocess.customizing_interprocess.custom_indexes" title="Building custom indexes">Building
 256           custom indexes</a> section.
 257         </p>
 258 </div>
 259 <div class="section">
 260 <div class="titlepage"><div><div><h4 class="title">
 261 <a name="interprocess.architecture.architecture_algorithm_to_managed.architecture_managed_memory"></a><a class="link" href="architecture.html#interprocess.architecture.architecture_algorithm_to_managed.architecture_managed_memory" title="Boost.Interprocess managed memory segments">Boost.Interprocess
 262         managed memory segments</a>
 263 </h4></div></div></div>
 264 <p>
 265           The <span class="bold"><strong>Boost.Interprocess</strong></span> managed memory
 266           segments that construct the shared memory/memory mapped file, place there
 267           the segment manager and forward the user requests to the segment manager.
 268           For example, <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_ma_idm45336641897392.html" title="Class template basic_managed_shared_memory">basic_managed_shared_memory</a></code>
 269           is a <span class="bold"><strong>Boost.Interprocess</strong></span> managed memory
 270           segment that works with shared memory. <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed_mapped_file.html" title="Class template basic_managed_mapped_file">basic_managed_mapped_file</a></code>
 271           works with memory mapped files, etc...
 272         </p>
 273 <p>
 274           Basically, the interface of a <span class="bold"><strong>Boost.Interprocess</strong></span>
 275           managed memory segment is the same as the <span class="bold"><strong>segment
 276           manager</strong></span> but it also offers functions to "open", "create",
 277           or "open or create" shared memory/memory-mapped files segments
 278           and initialize all needed resources. Managed memory segment classes are
 279           not built in shared memory or memory mapped files, they are normal C++
 280           classes that store a pointer to the segment manager (which is built in
 281           shared memory or memory mapped files).
 282         </p>
 283 <p>
 284           Apart from this, managed memory segments offer specific functions: <code class="computeroutput"><span class="identifier">managed_mapped_file</span></code> offers functions
 285           to flush memory contents to the file, <code class="computeroutput"><span class="identifier">managed_heap_memory</span></code>
 286           offers functions to expand the memory, etc...
 287         </p>
 288 <p>
 289           Most of the functions of <span class="bold"><strong>Boost.Interprocess</strong></span>
 290           managed memory segments can be shared between all managed memory segments,
 291           since many times they just forward the functions to the segment manager.
 292           Because of this, in <span class="bold"><strong>Boost.Interprocess</strong></span>
 293           all managed memory segments derive from a common class that implements
 294           memory-independent (shared memory, memory mapped files) functions: <a href="../../../boost/interprocess/detail/managed_memory_impl.hpp" target="_top">boost::interprocess::ipcdetail::basic_managed_memory_impl</a>
 295         </p>
 296 <p>
 297           Deriving from this class, <span class="bold"><strong>Boost.Interprocess</strong></span>
 298           implements several managed memory classes, for different memory backends:
 299         </p>
 300 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 301 <li class="listitem">
 302               <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_ma_idm45336641897392.html" title="Class template basic_managed_shared_memory">basic_managed_shared_memory</a></code>
 303               (for shared memory).
 304             </li>
 305 <li class="listitem">
 306               <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed_mapped_file.html" title="Class template basic_managed_mapped_file">basic_managed_mapped_file</a></code>
 307               (for memory mapped files).
 308             </li>
 309 <li class="listitem">
 310               <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed_heap_memory.html" title="Class template basic_managed_heap_memory">basic_managed_heap_memory</a></code>
 311               (for heap allocated memory).
 312             </li>
 313 <li class="listitem">
 314               <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_ma_idm45336642005904.html" title="Class template basic_managed_external_buffer">basic_managed_external_buffer</a></code>
 315               (for user provided external buffer).
 316             </li>
 317 </ul></div>
 318 </div>
 319 </div>
 320 <div class="section">
 321 <div class="titlepage"><div><div><h3 class="title">
 322 <a name="interprocess.architecture.allocators_containers"></a><a class="link" href="architecture.html#interprocess.architecture.allocators_containers" title="Allocators and containers">Allocators
 323       and containers</a>
 324 </h3></div></div></div>
 325 <div class="toc"><dl class="toc">
 326 <dt><span class="section"><a href="architecture.html#interprocess.architecture.allocators_containers.allocators">Boost.Interprocess
 327         allocators</a></span></dt>
 328 <dt><span class="section"><a href="architecture.html#interprocess.architecture.allocators_containers.implementation_segregated_storage_pools">Implementation
 329         of <span class="bold"><strong>Boost.Interprocess</strong></span> segregated storage
 330         pools</a></span></dt>
 331 <dt><span class="section"><a href="architecture.html#interprocess.architecture.allocators_containers.implementation_adaptive_pools">Implementation
 332         of <span class="bold"><strong>Boost.Interprocess</strong></span> adaptive pools</a></span></dt>
 333 <dt><span class="section"><a href="architecture.html#interprocess.architecture.allocators_containers.architecture_containers">Boost.Interprocess
 334         containers</a></span></dt>
 335 </dl></div>
 336 <div class="section">
 337 <div class="titlepage"><div><div><h4 class="title">
 338 <a name="interprocess.architecture.allocators_containers.allocators"></a><a class="link" href="architecture.html#interprocess.architecture.allocators_containers.allocators" title="Boost.Interprocess allocators">Boost.Interprocess
 339         allocators</a>
 340 </h4></div></div></div>
 341 <p>
 342           The <span class="bold"><strong>Boost.Interprocess</strong></span> STL-like allocators
 343           are fairly simple and follow the usual C++ allocator approach. Normally,
 344           allocators for STL containers are based above new/delete operators and
 345           above those, they implement pools, arenas and other allocation tricks.
 346         </p>
 347 <p>
 348           In <span class="bold"><strong>Boost.Interprocess</strong></span> allocators, the
 349           approach is similar, but all allocators are based on the <span class="bold"><strong>segment
 350           manager</strong></span>. The segment manager is the only one that provides from
 351           simple memory allocation to named object creations. <span class="bold"><strong>Boost.Interprocess</strong></span>
 352           allocators always store a pointer to the segment manager, so that they
 353           can obtain memory from the segment or share a common pool between allocators.
 354         </p>
 355 <p>
 356           As you can imagine, the member pointers of the allocator are not a raw
 357           pointers, but pointer types defined by the <code class="computeroutput"><span class="identifier">segment_manager</span><span class="special">::</span><span class="identifier">void_pointer</span></code>
 358           type. Apart from this, the <code class="computeroutput"><span class="identifier">pointer</span></code>
 359           typedef of <span class="bold"><strong>Boost.Interprocess</strong></span> allocators
 360           is also of the same type of <code class="computeroutput"><span class="identifier">segment_manager</span><span class="special">::</span><span class="identifier">void_pointer</span></code>.
 361         </p>
 362 <p>
 363           This means that if our allocation algorithm defines <code class="computeroutput"><span class="identifier">void_pointer</span></code>
 364           as <code class="computeroutput"><span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span></code>,
 365           <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocator</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
 366           will store an <code class="computeroutput"><span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="identifier">segment_manager</span><span class="special">&gt;</span></code> to point to the segment manager and
 367           the <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocator</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">pointer</span></code> type will be <code class="computeroutput"><span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>. This way, <span class="bold"><strong>Boost.Interprocess</strong></span>
 368           allocators can be placed in the memory segment managed by the segment manager,
 369           that is, shared memory, memory mapped files, etc...
 370         </p>
 371 </div>
 372 <div class="section">
 373 <div class="titlepage"><div><div><h4 class="title">
 374 <a name="interprocess.architecture.allocators_containers.implementation_segregated_storage_pools"></a><a class="link" href="architecture.html#interprocess.architecture.allocators_containers.implementation_segregated_storage_pools" title="Implementation of Boost.Interprocess segregated storage pools">Implementation
 375         of <span class="bold"><strong>Boost.Interprocess</strong></span> segregated storage
 376         pools</a>
 377 </h4></div></div></div>
 378 <p>
 379           Segregated storage pools are simple and follow the classic segregated storage
 380           algorithm.
 381         </p>
 382 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 383 <li class="listitem">
 384               The pool allocates chunks of memory using the segment manager's raw
 385               memory allocation functions.
 386             </li>
 387 <li class="listitem">
 388               The chunk contains a pointer to form a singly linked list of chunks.
 389               The pool will contain a pointer to the first chunk.
 390             </li>
 391 <li class="listitem">
 392               The rest of the memory of the chunk is divided in nodes of the requested
 393               size and no memory is used as payload for each node. Since the memory
 394               of a free node is not used that memory is used to place a pointer to
 395               form a singly linked list of free nodes. The pool has a pointer to
 396               the first free node.
 397             </li>
 398 <li class="listitem">
 399               Allocating a node is just taking the first free node from the list.
 400               If the list is empty, a new chunk is allocated, linked in the list
 401               of chunks and the new free nodes are linked in the free node list.
 402             </li>
 403 <li class="listitem">
 404               Deallocation returns the node to the free node list.
 405             </li>
 406 <li class="listitem">
 407               When the pool is destroyed, the list of chunks is traversed and memory
 408               is returned to the segment manager.
 409             </li>
 410 </ul></div>
 411 <p>
 412           The pool is implemented by the <a href="../../../boost/interprocess/allocators/detail/node_pool.hpp" target="_top">private_node_pool
 413           and shared_node_pool</a> classes.
 414         </p>
 415 </div>
 416 <div class="section">
 417 <div class="titlepage"><div><div><h4 class="title">
 418 <a name="interprocess.architecture.allocators_containers.implementation_adaptive_pools"></a><a class="link" href="architecture.html#interprocess.architecture.allocators_containers.implementation_adaptive_pools" title="Implementation of Boost.Interprocess adaptive pools">Implementation
 419         of <span class="bold"><strong>Boost.Interprocess</strong></span> adaptive pools</a>
 420 </h4></div></div></div>
 421 <p>
 422           Adaptive pools are a variation of segregated lists but they have a more
 423           complicated approach:
 424         </p>
 425 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 426 <li class="listitem">
 427               Instead of using raw allocation, the pool allocates <span class="bold"><strong>aligned</strong></span>
 428               chunks of memory using the segment manager. This is an <span class="bold"><strong>essential</strong></span>
 429               feature since a node can reach its chunk information applying a simple
 430               mask to its address.
 431             </li>
 432 <li class="listitem">
 433               The chunks contains pointers to form a doubly linked list of chunks
 434               and an additional pointer to create a singly linked list of free nodes
 435               placed on that chunk. So unlike the segregated storage algorithm, the
 436               free list of nodes is implemented <span class="bold"><strong>per chunk</strong></span>.
 437             </li>
 438 <li class="listitem">
 439               The pool maintains the chunks in increasing order of free nodes. This
 440               improves locality and minimizes the dispersion of node allocations
 441               across the chunks facilitating the creation of totally free chunks.
 442             </li>
 443 <li class="listitem">
 444               The pool has a pointer to the chunk with the minimum (but not zero)
 445               free nodes. This chunk is called the "active" chunk.
 446             </li>
 447 <li class="listitem">
 448               Allocating a node is just returning the first free node of the "active"
 449               chunk. The list of chunks is reordered according to the free nodes
 450               count. The pointer to the "active" pool is updated if necessary.
 451             </li>
 452 <li class="listitem">
 453               If the pool runs out of nodes, a new chunk is allocated, and pushed
 454               back in the list of chunks. The pointer to the "active" pool
 455               is updated if necessary.
 456             </li>
 457 <li class="listitem">
 458               Deallocation returns the node to the free node list of its chunk and
 459               updates the "active" pool accordingly.
 460             </li>
 461 <li class="listitem">
 462               If the number of totally free chunks exceeds the limit, chunks are
 463               returned to the segment manager.
 464             </li>
 465 <li class="listitem">
 466               When the pool is destroyed, the list of chunks is traversed and memory
 467               is returned to the segment manager.
 468             </li>
 469 </ul></div>
 470 <p>
 471           The adaptive pool is implemented by the <a href="../../../boost/interprocess/allocators/detail/adaptive_node_pool.hpp" target="_top">private_adaptive_node_pool
 472           and adaptive_node_pool</a> classes.
 473         </p>
 474 </div>
 475 <div class="section">
 476 <div class="titlepage"><div><div><h4 class="title">
 477 <a name="interprocess.architecture.allocators_containers.architecture_containers"></a><a class="link" href="architecture.html#interprocess.architecture.allocators_containers.architecture_containers" title="Boost.Interprocess containers">Boost.Interprocess
 478         containers</a>
 479 </h4></div></div></div>
 480 <p>
 481           <span class="bold"><strong>Boost.Interprocess</strong></span> containers are standard
 482           conforming counterparts of STL containers in <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span></code>
 483           namespace, but with these little details:
 484         </p>
 485 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 486 <li class="listitem">
 487               <span class="bold"><strong>Boost.Interprocess</strong></span> STL containers
 488               don't assume that memory allocated with an allocator can be deallocated
 489               with other allocator of the same type. They always compare allocators
 490               with <code class="computeroutput"><span class="keyword">operator</span><span class="special">==()</span></code>
 491               to know if this is possible.
 492             </li>
 493 <li class="listitem">
 494               The pointers of the internal structures of the <span class="bold"><strong>Boost.Interprocess</strong></span>
 495               containers are of the same type the <code class="computeroutput"><span class="identifier">pointer</span></code>
 496               type defined by the allocator of the container. This allows placing
 497               containers in managed memory segments mapped in different base addresses.
 498             </li>
 499 </ul></div>
 500 </div>
 501 </div>
 502 <div class="section">
 503 <div class="titlepage"><div><div><h3 class="title">
 504 <a name="interprocess.architecture.performance"></a><a class="link" href="architecture.html#interprocess.architecture.performance" title="Performance of Boost.Interprocess">Performance of
 505       Boost.Interprocess</a>
 506 </h3></div></div></div>
 507 <div class="toc"><dl class="toc">
 508 <dt><span class="section"><a href="architecture.html#interprocess.architecture.performance.performance_allocations">Performance
 509         of raw memory allocations</a></span></dt>
 510 <dt><span class="section"><a href="architecture.html#interprocess.architecture.performance.performance_named_allocation">Performance
 511         of named allocations</a></span></dt>
 512 </dl></div>
 513 <p>
 514         This section tries to explain the performance characteristics of <span class="bold"><strong>Boost.Interprocess</strong></span>, so that you can optimize <span class="bold"><strong>Boost.Interprocess</strong></span> usage if you need more performance.
 515       </p>
 516 <div class="section">
 517 <div class="titlepage"><div><div><h4 class="title">
 518 <a name="interprocess.architecture.performance.performance_allocations"></a><a class="link" href="architecture.html#interprocess.architecture.performance.performance_allocations" title="Performance of raw memory allocations">Performance
 519         of raw memory allocations</a>
 520 </h4></div></div></div>
 521 <p>
 522           You can have two types of raw memory allocations with <span class="bold"><strong>Boost.Interprocess</strong></span>
 523           classes:
 524         </p>
 525 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 526 <li class="listitem">
 527               <span class="bold"><strong>Explicit</strong></span>: The user calls <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code>
 528               and <code class="computeroutput"><span class="identifier">deallocate</span><span class="special">()</span></code>
 529               functions of managed_shared_memory/managed_mapped_file... managed memory
 530               segments. This call is translated to a <code class="computeroutput"><span class="identifier">MemoryAlgorithm</span><span class="special">::</span><span class="identifier">allocate</span><span class="special">()</span></code> function, which means that you will
 531               need just the time that the memory algorithm associated with the managed
 532               memory segment needs to allocate data.
 533             </li>
 534 <li class="listitem">
 535               <span class="bold"><strong>Implicit</strong></span>: For example, you are using
 536               <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocator</span><span class="special">&lt;...&gt;</span></code>
 537               with <span class="bold"><strong>Boost.Interprocess</strong></span> containers.
 538               This allocator calls the same <code class="computeroutput"><span class="identifier">MemoryAlgorithm</span><span class="special">::</span><span class="identifier">allocate</span><span class="special">()</span></code> function than the explicit method,
 539               <span class="bold"><strong>every</strong></span> time a vector/string has to
 540               reallocate its buffer or <span class="bold"><strong>every</strong></span> time
 541               you insert an object in a node container.
 542             </li>
 543 </ul></div>
 544 <p>
 545           If you see that memory allocation is a bottleneck in your application,
 546           you have these alternatives:
 547         </p>
 548 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 549 <li class="listitem">
 550               If you use map/set associative containers, try using <code class="computeroutput"><span class="identifier">flat_map</span></code> family instead of the map
 551               family if you mainly do searches and the insertion/removal is mainly
 552               done in an initialization phase. The overhead is now when the ordered
 553               vector has to reallocate its storage and move data. You can also call
 554               the <code class="computeroutput"><span class="identifier">reserve</span><span class="special">()</span></code>
 555               method of these containers when you know beforehand how much data you
 556               will insert. However in these containers iterators are invalidated
 557               in insertions so this substitution is only effective in some applications.
 558             </li>
 559 <li class="listitem">
 560               Use a <span class="bold"><strong>Boost.Interprocess</strong></span> pooled allocator
 561               for node containers, because pooled allocators call <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> only when the pool runs out of nodes.
 562               This is pretty efficient (much more than the current default general-purpose
 563               algorithm) and this can save a lot of memory. See <a class="link" href="allocators_containers.html#interprocess.allocators_containers.stl_allocators_segregated_storage" title="Segregated storage node allocators">Segregated
 564               storage node allocators</a> and <a class="link" href="allocators_containers.html#interprocess.allocators_containers.stl_allocators_adaptive" title="Adaptive pool node allocators">Adaptive
 565               node allocators</a> for more information.
 566             </li>
 567 <li class="listitem">
 568               Write your own memory algorithm. If you have experience with memory
 569               allocation algorithms and you think another algorithm is better suited
 570               than the default one for your application, you can specify it in all
 571               <span class="bold"><strong>Boost.Interprocess</strong></span> managed memory
 572               segments. See the section <a class="link" href="customizing_interprocess.html#interprocess.customizing_interprocess.custom_interprocess_alloc" title="Writing a new shared memory allocation algorithm">Writing
 573               a new shared memory allocation algorithm</a> to know how to do this.
 574               If you think its better than the default one for general-purpose applications,
 575               be polite and donate it to <span class="bold"><strong>Boost.Interprocess</strong></span>
 576               to make it default!
 577             </li>
 578 </ul></div>
 579 </div>
 580 <div class="section">
 581 <div class="titlepage"><div><div><h4 class="title">
 582 <a name="interprocess.architecture.performance.performance_named_allocation"></a><a class="link" href="architecture.html#interprocess.architecture.performance.performance_named_allocation" title="Performance of named allocations">Performance
 583         of named allocations</a>
 584 </h4></div></div></div>
 585 <p>
 586           <span class="bold"><strong>Boost.Interprocess</strong></span> allows the same parallelism
 587           as two threads writing to a common structure, except when the user creates/searches
 588           named/unique objects. The steps when creating a named object are these:
 589         </p>
 590 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 591 <li class="listitem">
 592               Lock a recursive mutex (so that you can make named allocations inside
 593               the constructor of the object to be created).
 594             </li>
 595 <li class="listitem">
 596               Try to insert the [name pointer, object information] in the name/object
 597               index. This lookup has to assure that the name has not been used before.
 598               This is achieved calling <code class="computeroutput"><span class="identifier">insert</span><span class="special">()</span></code> function in the index. So the time
 599               this requires is dependent on the index type (ordered vector, tree,
 600               hash...). This can require a call to the memory algorithm allocation
 601               function if the index has to be reallocated, it's a node allocator,
 602               uses pooled allocations...
 603             </li>
 604 <li class="listitem">
 605               Allocate a single buffer to hold the name of the object, the object
 606               itself, and meta-data for destruction (number of objects, etc...).
 607             </li>
 608 <li class="listitem">
 609               Call the constructors of the object being created. If it's an array,
 610               one constructor per array element.
 611             </li>
 612 <li class="listitem">
 613               Unlock the recursive mutex.
 614             </li>
 615 </ul></div>
 616 <p>
 617           The steps when destroying a named object using the name of the object (<code class="computeroutput"><span class="identifier">destroy</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;(</span><span class="identifier">name</span><span class="special">)</span></code>)
 618           are these:
 619         </p>
 620 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 621 <li class="listitem">
 622               Lock a recursive mutex .
 623             </li>
 624 <li class="listitem">
 625               Search in the index the entry associated to that name. Copy that information
 626               and erase the index entry. This is done using <code class="computeroutput"><span class="identifier">find</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">key_type</span> <span class="special">&amp;)</span></code>
 627               and <code class="computeroutput"><span class="identifier">erase</span><span class="special">(</span><span class="identifier">iterator</span><span class="special">)</span></code>
 628               members of the index. This can require element reordering if the index
 629               is a balanced tree, an ordered vector...
 630             </li>
 631 <li class="listitem">
 632               Call the destructor of the object (many if it's an array).
 633             </li>
 634 <li class="listitem">
 635               Deallocate the memory buffer containing the name, metadata and the
 636               object itself using the allocation algorithm.
 637             </li>
 638 <li class="listitem">
 639               Unlock the recursive mutex.
 640             </li>
 641 </ul></div>
 642 <p>
 643           The steps when destroying a named object using the pointer of the object
 644           (<code class="computeroutput"><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">T</span> <span class="special">*</span><span class="identifier">ptr</span><span class="special">)</span></code>) are these:
 645         </p>
 646 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 647 <li class="listitem">
 648               Lock a recursive mutex .
 649             </li>
 650 <li class="listitem">
 651               Depending on the index type, this can be different:
 652               <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
 653 <li class="listitem">
 654                     If the index is a node index, (marked with <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">is_node_index</span></code>
 655                     specialization): Take the iterator stored near the object and
 656                     call <code class="computeroutput"><span class="identifier">erase</span><span class="special">(</span><span class="identifier">iterator</span><span class="special">)</span></code>.
 657                     This can require element reordering if the index is a balanced
 658                     tree, an ordered vector...
 659                   </li>
 660 <li class="listitem">
 661                     If it's not an node index: Take the name stored near the object
 662                     and erase the index entry calling `erase(const key &amp;). This
 663                     can require element reordering if the index is a balanced tree,
 664                     an ordered vector...
 665                   </li>
 666 </ul></div>
 667             </li>
 668 <li class="listitem">
 669               Call the destructor of the object (many if it's an array).
 670             </li>
 671 <li class="listitem">
 672               Deallocate the memory buffer containing the name, metadata and the
 673               object itself using the allocation algorithm.
 674             </li>
 675 <li class="listitem">
 676               Unlock the recursive mutex.
 677             </li>
 678 </ul></div>
 679 <p>
 680           If you see that the performance is not good enough you have these alternatives:
 681         </p>
 682 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 683 <li class="listitem">
 684               Maybe the problem is that the lock time is too big and it hurts parallelism.
 685               Try to reduce the number of named objects in the global index and if
 686               your application serves several clients try to build a new managed
 687               memory segment for each one instead of using a common one.
 688             </li>
 689 <li class="listitem">
 690               Use another <span class="bold"><strong>Boost.Interprocess</strong></span> index
 691               type if you feel the default one is not fast enough. If you are not
 692               still satisfied, write your own index type. See <a class="link" href="customizing_interprocess.html#interprocess.customizing_interprocess.custom_indexes" title="Building custom indexes">Building
 693               custom indexes</a> for this.
 694             </li>
 695 <li class="listitem">
 696               Destruction via pointer is at least as fast as using the name of the
 697               object and can be faster (in node containers, for example). So if your
 698               problem is that you make at lot of named destructions, try to use the
 699               pointer. If the index is a node index you can save some time.
 700             </li>
 701 </ul></div>
 702 </div>
 703 </div>
 704 </div>
 705 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 706 <td align="left"></td>
 707 <td align="right"><div class="copyright-footer">Copyright &#169; 2005-2015 Ion Gaztanaga<p>
 708         Distributed under the Boost Software License, Version 1.0. (See accompanying
 709         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>)
 710       </p>
 711 </div></td>
 712 </tr></table>
 713 <hr>
 714 <div class="spirit-nav">
 715 <a accesskey="p" href="interprocess_smart_ptr.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../interprocess.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="customizing_interprocess.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
 716 </div>
 717 </body>
 718 </html>