doc/html/interprocess/managed_memory_segments.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Managed Memory Segments</title>
   5 <link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
   8 <link rel="up" href="../interprocess.html" title="Chapter&#160;14.&#160;Boost.Interprocess">
   9 <link rel="prev" href="synchronization_mechanisms.html" title="Synchronization mechanisms">
  10 <link rel="next" href="allocators_containers.html" title="Allocators, containers and memory allocation algorithms">
  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="synchronization_mechanisms.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="allocators_containers.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="interprocess.managed_memory_segments"></a><a class="link" href="managed_memory_segments.html" title="Managed Memory Segments">Managed Memory Segments</a>
  28 </h2></div></div></div>
  29 <div class="toc"><dl class="toc">
  30 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.making_ipc_easy">Making
  31       Interprocess Data Communication Easy</a></span></dt>
  32 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory">Managed
  33       Shared Memory</a></span></dt>
  34 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_mapped_files">Managed
  35       Mapped File</a></span></dt>
  36 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features">Managed
  37       Memory Segment Features</a></span></dt>
  38 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features">Managed
  39       Memory Segment Advanced Features</a></span></dt>
  40 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer">Managed
  41       Heap Memory And Managed External Buffer</a></span></dt>
  42 </dl></div>
  43 <div class="section">
  44 <div class="titlepage"><div><div><h3 class="title">
  45 <a name="interprocess.managed_memory_segments.making_ipc_easy"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.making_ipc_easy" title="Making Interprocess Data Communication Easy">Making
  46       Interprocess Data Communication Easy</a>
  47 </h3></div></div></div>
  48 <div class="toc"><dl class="toc">
  49 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.making_ipc_easy.managed_memory_segments_intro">Introduction</a></span></dt>
  50 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.making_ipc_easy.managed_memory_segment_int">Declaration
  51         of managed memory segment classes</a></span></dt>
  52 </dl></div>
  53 <div class="section">
  54 <div class="titlepage"><div><div><h4 class="title">
  55 <a name="interprocess.managed_memory_segments.making_ipc_easy.managed_memory_segments_intro"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.making_ipc_easy.managed_memory_segments_intro" title="Introduction">Introduction</a>
  56 </h4></div></div></div>
  57 <p>
  58           As we have seen, <span class="bold"><strong>Boost.Interprocess</strong></span> offers
  59           some basic classes to create shared memory objects and file mappings and
  60           map those mappable classes to the process' address space.
  61         </p>
  62 <p>
  63           However, managing those memory segments is not not easy for non-trivial
  64           tasks. A mapped region is a fixed-length memory buffer and creating and
  65           destroying objects of any type dynamically, requires a lot of work, since
  66           it would require programming a memory management algorithm to allocate
  67           portions of that segment. Many times, we also want to associate names to
  68           objects created in shared memory, so all the processes can find the object
  69           using the name.
  70         </p>
  71 <p>
  72           <span class="bold"><strong>Boost.Interprocess</strong></span> offers 4 managed memory
  73           segment classes:
  74         </p>
  75 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  76 <li class="listitem">
  77               To manage a shared memory mapped region (<span class="bold"><strong>basic_managed_shared_memory</strong></span>
  78               class).
  79             </li>
  80 <li class="listitem">
  81               To manage a memory mapped file (<span class="bold"><strong>basic_managed_mapped_file</strong></span>).
  82             </li>
  83 <li class="listitem">
  84               To manage a heap allocated (<code class="computeroutput"><span class="keyword">operator</span>
  85               <span class="keyword">new</span></code>) memory buffer (<span class="bold"><strong>basic_managed_heap_memory</strong></span> class).
  86             </li>
  87 <li class="listitem">
  88               To manage a user provided fixed size buffer (<span class="bold"><strong>basic_managed_external_buffer</strong></span>
  89               class).
  90             </li>
  91 </ul></div>
  92 <p>
  93           The first two classes manage memory segments that can be shared between
  94           processes. The third is useful to create complex data-bases to be sent
  95           though other mechanisms like message queues to other processes. The fourth
  96           class can manage any fixed size memory buffer. The first two classes will
  97           be explained in the next two sections. <span class="bold"><strong>basic_managed_heap_memory</strong></span>
  98           and <span class="bold"><strong>basic_managed_external_buffer</strong></span> will
  99           be explained later.
 100         </p>
 101 <p>
 102           The most important services of a managed memory segment are:
 103         </p>
 104 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 105 <li class="listitem">
 106               Dynamic allocation of portions of a memory the segment.
 107             </li>
 108 <li class="listitem">
 109               Construction of C++ objects in the memory segment. These objects can
 110               be anonymous or we can associate a name to them.
 111             </li>
 112 <li class="listitem">
 113               Searching capabilities for named objects.
 114             </li>
 115 <li class="listitem">
 116               Customization of many features: memory allocation algorithm, index
 117               types or character types.
 118             </li>
 119 <li class="listitem">
 120               Atomic constructions and destructions so that if the segment is shared
 121               between two processes it's impossible to create two objects associated
 122               with the same name, simplifying synchronization.
 123             </li>
 124 </ul></div>
 125 </div>
 126 <div class="section">
 127 <div class="titlepage"><div><div><h4 class="title">
 128 <a name="interprocess.managed_memory_segments.making_ipc_easy.managed_memory_segment_int"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.making_ipc_easy.managed_memory_segment_int" title="Declaration of managed memory segment classes">Declaration
 129         of managed memory segment classes</a>
 130 </h4></div></div></div>
 131 <p>
 132           All <span class="bold"><strong>Boost.Interprocess</strong></span> managed memory
 133           segment classes are templatized classes that can be customized by the user:
 134         </p>
 135 <pre class="programlisting"><span class="keyword">template</span>
 136       <span class="special">&lt;</span>
 137          <span class="keyword">class</span> <span class="identifier">CharType</span><span class="special">,</span>
 138          <span class="keyword">class</span> <span class="identifier">MemoryAlgorithm</span><span class="special">,</span>
 139          <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>
 140       <span class="special">&gt;</span>
 141 <span class="keyword">class</span> <span class="identifier">basic_managed_shared_memory</span> <span class="special">/</span> <span class="identifier">basic_managed_mapped_file</span> <span class="special">/</span>
 142       <span class="identifier">basic_managed_heap_memory</span>   <span class="special">/</span> <span class="identifier">basic_external_buffer</span><span class="special">;</span>
 143 </pre>
 144 <p>
 145           These classes can be customized with the following template parameters:
 146         </p>
 147 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 148 <li class="listitem">
 149               <span class="bold"><strong>CharType</strong></span> is the type of the character
 150               that will be used to identify the created named objects (for example,
 151               <span class="bold"><strong>char</strong></span> or <span class="bold"><strong>wchar_t</strong></span>)
 152             </li>
 153 <li class="listitem">
 154               <span class="bold"><strong>MemoryAlgorithm</strong></span> is the memory algorithm
 155               used to allocate portions of the segment (for example, rbtree_best_fit
 156               ). The internal typedefs of the memory algorithm also define:
 157               <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
 158 <li class="listitem">
 159                     The synchronization type (<code class="computeroutput"><span class="identifier">MemoryAlgorithm</span><span class="special">::</span><span class="identifier">mutex_family</span></code>)
 160                     to be used in all allocation operations. This allows the use
 161                     of user-defined mutexes or avoiding internal locking (maybe code
 162                     will be externally synchronized by the user).
 163                   </li>
 164 <li class="listitem">
 165                     The Pointer type (<code class="computeroutput"><span class="identifier">MemoryAlgorithm</span><span class="special">::</span><span class="identifier">void_pointer</span></code>)
 166                     to be used by the memory allocation algorithm or additional helper
 167                     structures (like a map to maintain object/name associations).
 168                     All STL compatible allocators and containers to be used with
 169                     this managed memory segment will use this pointer type. The pointer
 170                     type will define if the managed memory segment can be mapped
 171                     between several processes. For example, if <code class="computeroutput"><span class="identifier">void_pointer</span></code>
 172                     is <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> we will be able to map the
 173                     managed segment in different base addresses in each process.
 174                     If <code class="computeroutput"><span class="identifier">void_pointer</span></code>
 175                     is <code class="computeroutput"><span class="keyword">void</span><span class="special">*</span></code>
 176                     only fixed address mapping could be used.
 177                   </li>
 178 <li class="listitem">
 179                     See <a class="link" href="customizing_interprocess.html#interprocess.customizing_interprocess.custom_interprocess_alloc" title="Writing a new shared memory allocation algorithm">Writing
 180                     a new memory allocation algorithm</a> for more details about
 181                     memory algorithms.
 182                   </li>
 183 </ul></div>
 184             </li>
 185 <li class="listitem">
 186               <span class="bold"><strong>IndexType</strong></span> is the type of index that
 187               will be used to store the name-object association (for example, a map,
 188               a hash-map, or an ordered vector).
 189             </li>
 190 </ul></div>
 191 <p>
 192           This way, we can use <code class="computeroutput"><span class="keyword">char</span></code>
 193           or <code class="computeroutput"><span class="keyword">wchar_t</span></code> strings to identify
 194           created C++ objects in the memory segment, we can plug new shared memory
 195           allocation algorithms, and use the index type that is best suited to our
 196           needs.
 197         </p>
 198 </div>
 199 </div>
 200 <div class="section">
 201 <div class="titlepage"><div><div><h3 class="title">
 202 <a name="interprocess.managed_memory_segments.managed_shared_memory"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory" title="Managed Shared Memory">Managed
 203       Shared Memory</a>
 204 </h3></div></div></div>
 205 <div class="toc"><dl class="toc">
 206 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.managed_memory_common_shm">Common
 207         Managed Shared Memory Classes</a></span></dt>
 208 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.constructing_managed_shared_memories">Constructing
 209         Managed Shared Memory</a></span></dt>
 210 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.windows_managed_memory_common_shm">Using
 211         native windows shared memory</a></span></dt>
 212 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.xsi_managed_memory_common_shm">Using
 213         XSI (system V) shared memory</a></span></dt>
 214 </dl></div>
 215 <div class="section">
 216 <div class="titlepage"><div><div><h4 class="title">
 217 <a name="interprocess.managed_memory_segments.managed_shared_memory.managed_memory_common_shm"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.managed_memory_common_shm" title="Common Managed Shared Memory Classes">Common
 218         Managed Shared Memory Classes</a>
 219 </h4></div></div></div>
 220 <p>
 221           As seen, <span class="bold"><strong>basic_managed_shared_memory</strong></span> offers
 222           a great variety of customization. But for the average user, a common, default
 223           shared memory named object creation is needed. Because of this, <span class="bold"><strong>Boost.Interprocess</strong></span> defines the most common managed
 224           shared memory specializations:
 225         </p>
 226 <pre class="programlisting"><span class="comment">//!Defines a managed shared memory with c-strings as keys for named objects,</span>
 227 <span class="comment">//!the default memory algorithm (with process-shared mutexes,</span>
 228 <span class="comment">//!and offset_ptr as internal pointers) as memory allocation algorithm</span>
 229 <span class="comment">//!and the default index type as the index.</span>
 230 <span class="comment">//!This class allows the shared memory to be mapped in different base</span>
 231 <span class="comment">//!in different processes</span>
 232 <span class="keyword">typedef</span>
 233    <span class="identifier">basic_managed_shared_memory</span><span class="special">&lt;</span><span class="keyword">char</span>
 234                               <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">memory</span> <span class="identifier">algorithm</span> <span class="identifier">defining</span> <span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="identifier">as</span> <span class="identifier">void_pointer</span><span class="special">*/</span>
 235                               <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">index</span> <span class="identifier">type</span><span class="special">*/&gt;</span>
 236    <span class="identifier">managed_shared_memory</span><span class="special">;</span>
 237
 238 <span class="comment">//!Defines a managed shared memory with wide strings as keys for named objects,</span>
 239 <span class="comment">//!the default memory algorithm (with process-shared mutexes,</span>
 240 <span class="comment">//!and offset_ptr as internal pointers) as memory allocation algorithm</span>
 241 <span class="comment">//!and the default index type as the index.</span>
 242 <span class="comment">//!This class allows the shared memory to be mapped in different base</span>
 243 <span class="comment">//!in different processes</span>
 244 <span class="keyword">typedef</span>
 245    <span class="identifier">basic_managed_shared_memory</span><span class="special">&lt;</span><span class="keyword">wchar_t</span>
 246                               <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">memory</span> <span class="identifier">algorithm</span> <span class="identifier">defining</span> <span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="identifier">as</span> <span class="identifier">void_pointer</span><span class="special">*/</span>
 247                               <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">index</span> <span class="identifier">type</span><span class="special">*/&gt;</span>
 248    <span class="identifier">wmanaged_shared_memory</span><span class="special">;</span>
 249 </pre>
 250 <p>
 251           <code class="computeroutput"><span class="identifier">managed_shared_memory</span></code> allocates
 252           objects in shared memory associated with a c-string and <code class="computeroutput"><span class="identifier">wmanaged_shared_memory</span></code>
 253           allocates objects in shared memory associated with a wchar_t null terminated
 254           string. Both define the pointer type 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> so they can be used to map the shared
 255           memory at different base addresses in different processes.
 256         </p>
 257 <p>
 258           If the user wants to map the shared memory in the same address in all processes
 259           and want to use raw pointers internally instead of offset pointers, <span class="bold"><strong>Boost.Interprocess</strong></span> defines the following types:
 260         </p>
 261 <pre class="programlisting"><span class="comment">//!Defines a managed shared memory with c-strings as keys for named objects,</span>
 262 <span class="comment">//!the default memory algorithm (with process-shared mutexes,</span>
 263 <span class="comment">//!and offset_ptr as internal pointers) as memory allocation algorithm</span>
 264 <span class="comment">//!and the default index type as the index.</span>
 265 <span class="comment">//!This class allows the shared memory to be mapped in different base</span>
 266 <span class="comment">//!in different processes*/</span>
 267 <span class="keyword">typedef</span> <span class="identifier">basic_managed_shared_memory</span>
 268    <span class="special">&lt;</span><span class="keyword">char</span>
 269    <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">memory</span> <span class="identifier">algorithm</span> <span class="identifier">defining</span> <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">as</span> <span class="identifier">void_pointer</span><span class="special">*/</span>
 270    <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">index</span> <span class="identifier">type</span><span class="special">*/&gt;</span>
 271 <span class="identifier">fixed_managed_shared_memory</span><span class="special">;</span>
 272
 273 <span class="comment">//!Defines a managed shared memory with wide strings as keys for named objects,</span>
 274 <span class="comment">//!the default memory algorithm (with process-shared mutexes,</span>
 275 <span class="comment">//!and offset_ptr as internal pointers) as memory allocation algorithm</span>
 276 <span class="comment">//!and the default index type as the index.</span>
 277 <span class="comment">//!This class allows the shared memory to be mapped in different base</span>
 278 <span class="comment">//!in different processes</span>
 279 <span class="keyword">typedef</span> <span class="identifier">basic_managed_shared_memory</span>
 280    <span class="special">&lt;</span><span class="keyword">wchar_t</span>
 281    <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">memory</span> <span class="identifier">algorithm</span> <span class="identifier">defining</span> <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">as</span> <span class="identifier">void_pointer</span><span class="special">*/</span>
 282    <span class="special">,/*</span><span class="identifier">Default</span> <span class="identifier">index</span> <span class="identifier">type</span><span class="special">*/&gt;</span>
 283 <span class="identifier">wfixed_managed_shared_memory</span><span class="special">;</span>
 284 </pre>
 285 </div>
 286 <div class="section">
 287 <div class="titlepage"><div><div><h4 class="title">
 288 <a name="interprocess.managed_memory_segments.managed_shared_memory.constructing_managed_shared_memories"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.constructing_managed_shared_memories" title="Constructing Managed Shared Memory">Constructing
 289         Managed Shared Memory</a>
 290 </h4></div></div></div>
 291 <p>
 292           Managed shared memory is an advanced class that combines a shared memory
 293           object and a mapped region that covers all the shared memory object. That
 294           means that when we <span class="bold"><strong>create</strong></span> a new managed
 295           shared memory:
 296         </p>
 297 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 298 <li class="listitem">
 299               A new shared memory object is created.
 300             </li>
 301 <li class="listitem">
 302               The whole shared memory object is mapped in the process' address space.
 303             </li>
 304 <li class="listitem">
 305               Some helper objects are constructed (name-object index, internal synchronization
 306               objects, internal variables...) in the mapped region to implement managed
 307               memory segment features.
 308             </li>
 309 </ul></div>
 310 <p>
 311           When we <span class="bold"><strong>open</strong></span> a managed shared memory
 312         </p>
 313 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 314 <li class="listitem">
 315               A shared memory object is opened.
 316             </li>
 317 <li class="listitem">
 318               The whole shared memory object is mapped in the process' address space.
 319             </li>
 320 </ul></div>
 321 <p>
 322           To use a managed shared memory, you must include the following header:
 323         </p>
 324 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 325 </pre>
 326 <pre class="programlisting"><span class="comment">//1.  Creates a new shared memory object</span>
 327 <span class="comment">//    called "MySharedMemory".</span>
 328 <span class="comment">//2.  Maps the whole object to this</span>
 329 <span class="comment">//    process' address space.</span>
 330 <span class="comment">//3.  Constructs some objects in shared memory</span>
 331 <span class="comment">//    to implement managed features.</span>
 332 <span class="comment">//!!  If anything fails, throws interprocess_exception</span>
 333 <span class="comment">//</span>
 334 <span class="identifier">managed_shared_memory</span> <span class="identifier">segment</span>      <span class="special">(</span> <span class="identifier">create_only</span>
 335                                    <span class="special">,</span> <span class="string">"MySharedMemory"</span> <span class="comment">//Shared memory object name</span>
 336                                    <span class="special">,</span> <span class="number">65536</span><span class="special">);</span>          <span class="comment">//Shared memory object size in bytes</span>
 337 </pre>
 338 <pre class="programlisting"><span class="comment">//1.  Opens a shared memory object</span>
 339 <span class="comment">//    called "MySharedMemory".</span>
 340 <span class="comment">//2.  Maps the whole object to this</span>
 341 <span class="comment">//    process' address space.</span>
 342 <span class="comment">//3.  Obtains pointers to constructed internal objects</span>
 343 <span class="comment">//    to implement managed features.</span>
 344 <span class="comment">//!!  If anything fails, throws interprocess_exception</span>
 345 <span class="comment">//</span>
 346 <span class="identifier">managed_shared_memory</span> <span class="identifier">segment</span>      <span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span>       <span class="string">"MySharedMemory"</span><span class="special">);//</span><span class="identifier">Shared</span> <span class="identifier">memory</span> <span class="identifier">object</span> <span class="identifier">name</span>
 347 </pre>
 348 <pre class="programlisting"><span class="comment">//1.  If the segment was previously created</span>
 349 <span class="comment">//    equivalent to "open_only" (size is ignored).</span>
 350 <span class="comment">//2.  Otherwise, equivalent to "create_only"</span>
 351 <span class="comment">//!!  If anything fails, throws interprocess_exception</span>
 352 <span class="comment">//</span>
 353 <span class="identifier">managed_shared_memory</span> <span class="identifier">segment</span>      <span class="special">(</span> <span class="identifier">open_or_create</span>
 354                                    <span class="special">,</span> <span class="string">"MySharedMemory"</span> <span class="comment">//Shared memory object name</span>
 355                                    <span class="special">,</span> <span class="number">65536</span><span class="special">);</span>          <span class="comment">//Shared memory object size in bytes</span>
 356 </pre>
 357 <p>
 358           When the <code class="computeroutput"><span class="identifier">managed_shared_memory</span></code>
 359           object is destroyed, the shared memory object is automatically unmapped,
 360           and all the resources are freed. To remove the shared memory object from
 361           the system you must use the <code class="computeroutput"><span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span></code>
 362           function. Shared memory object removing might fail if any process still
 363           has the shared memory object mapped.
 364         </p>
 365 <p>
 366           The user can also map the managed shared memory in a fixed address. This
 367           option is essential when using using <code class="computeroutput"><span class="identifier">fixed_managed_shared_memory</span></code>.
 368           To do this, just add the mapping address as an extra parameter:
 369         </p>
 370 <pre class="programlisting"><span class="identifier">fixed_managed_shared_memory</span> <span class="identifier">segment</span>      <span class="special">(</span><span class="identifier">open_only</span>      <span class="special">,</span><span class="string">"MyFixedAddressSharedMemory"</span> <span class="comment">//Shared memory object name</span>
 371    <span class="special">,(</span><span class="keyword">void</span><span class="special">*)</span><span class="number">0x30000000</span>            <span class="comment">//Mapping address</span>
 372 </pre>
 373 </div>
 374 <div class="section">
 375 <div class="titlepage"><div><div><h4 class="title">
 376 <a name="interprocess.managed_memory_segments.managed_shared_memory.windows_managed_memory_common_shm"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.windows_managed_memory_common_shm" title="Using native windows shared memory">Using
 377         native windows shared memory</a>
 378 </h4></div></div></div>
 379 <p>
 380           Windows users might also want to use native windows shared memory instead
 381           of the portable <code class="computeroutput"><a class="link" href="../boost/interprocess/shared_memory_object.html" title="Class shared_memory_object">shared_memory_object</a></code>
 382           managed memory. This is achieved through the <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed__idp65413104.html" title="Class template basic_managed_windows_shared_memory">basic_managed_windows_shared_memory</a></code>
 383           class. To use it just include:
 384         </p>
 385 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_windows_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 386 </pre>
 387 <p>
 388           This class has the same interface as <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed__idp65355360.html" title="Class template basic_managed_shared_memory">basic_managed_shared_memory</a></code>
 389           but uses native windows shared memory. Note that this managed class has
 390           the same lifetime issues as the windows shared memory: when the last process
 391           attached to the windows shared memory is detached from the memory (or ends/crashes)
 392           the memory is destroyed. So there is no persistence support for windows
 393           shared memory.
 394         </p>
 395 <p>
 396           To communicate between system services and user applications using <code class="computeroutput"><span class="identifier">managed_windows_shared_memory</span></code>, please
 397           read the explanations given in chapter <a class="link" href="sharedmemorybetweenprocesses.html#interprocess.sharedmemorybetweenprocesses.sharedmemory.windows_shared_memory" title="Native windows shared memory">Native
 398           windows shared memory</a>.
 399         </p>
 400 </div>
 401 <div class="section">
 402 <div class="titlepage"><div><div><h4 class="title">
 403 <a name="interprocess.managed_memory_segments.managed_shared_memory.xsi_managed_memory_common_shm"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_shared_memory.xsi_managed_memory_common_shm" title="Using XSI (system V) shared memory">Using
 404         XSI (system V) shared memory</a>
 405 </h4></div></div></div>
 406 <p>
 407           Unix users might also want to use XSI (system V) instead of the portable
 408           <code class="computeroutput"><a class="link" href="../boost/interprocess/shared_memory_object.html" title="Class shared_memory_object">shared_memory_object</a></code>
 409           managed memory. This is achieved through the <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed__idp65461824.html" title="Class template basic_managed_xsi_shared_memory">basic_managed_xsi_shared_memory</a></code>
 410           class. To use it just include:
 411         </p>
 412 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_xsi_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 413 </pre>
 414 <p>
 415           This class has nearly the same interface as <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed__idp65355360.html" title="Class template basic_managed_shared_memory">basic_managed_shared_memory</a></code>
 416           but uses XSI shared memory as backend.
 417         </p>
 418 </div>
 419 <p>
 420         For more information about managed XSI shared memory capabilities, see <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed__idp65461824.html" title="Class template basic_managed_xsi_shared_memory">basic_managed_xsi_shared_memory</a></code>
 421         class reference.
 422       </p>
 423 </div>
 424 <div class="section">
 425 <div class="titlepage"><div><div><h3 class="title">
 426 <a name="interprocess.managed_memory_segments.managed_mapped_files"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_mapped_files" title="Managed Mapped File">Managed
 427       Mapped File</a>
 428 </h3></div></div></div>
 429 <div class="toc"><dl class="toc">
 430 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_mapped_files.managed_memory_common_mfile">Common
 431         Managed Mapped Files</a></span></dt>
 432 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_mapped_files.constructing_managed_mapped_files">Constructing
 433         Managed Mapped Files</a></span></dt>
 434 </dl></div>
 435 <div class="section">
 436 <div class="titlepage"><div><div><h4 class="title">
 437 <a name="interprocess.managed_memory_segments.managed_mapped_files.managed_memory_common_mfile"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_mapped_files.managed_memory_common_mfile" title="Common Managed Mapped Files">Common
 438         Managed Mapped Files</a>
 439 </h4></div></div></div>
 440 <p>
 441           As seen, <span class="bold"><strong>basic_managed_mapped_file</strong></span> offers
 442           a great variety of customization. But for the average user, a common, default
 443           shared memory named object creation is needed. Because of this, <span class="bold"><strong>Boost.Interprocess</strong></span> defines the most common managed
 444           mapped file specializations:
 445         </p>
 446 <pre class="programlisting"><span class="comment">//Named object creation managed memory segment</span>
 447 <span class="comment">//All objects are constructed in the memory-mapped file</span>
 448 <span class="comment">//   Names are c-strings,</span>
 449 <span class="comment">//   Default memory management algorithm(rbtree_best_fit with no mutexes)</span>
 450 <span class="comment">//   Name-object mappings are stored in the default index type (flat_map)</span>
 451 <span class="keyword">typedef</span> <span class="identifier">basic_managed_mapped_file</span> <span class="special">&lt;</span>
 452    <span class="keyword">char</span><span class="special">,</span>
 453    <span class="identifier">rbtree_best_fit</span><span class="special">&lt;</span><span class="identifier">mutex_family</span><span class="special">,</span> <span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;,</span>
 454    <span class="identifier">flat_map_index</span>
 455    <span class="special">&gt;</span>  <span class="identifier">managed_mapped_file</span><span class="special">;</span>
 456
 457 <span class="comment">//Named object creation managed memory segment</span>
 458 <span class="comment">//All objects are constructed in the memory-mapped file</span>
 459 <span class="comment">//   Names are wide-strings,</span>
 460 <span class="comment">//   Default memory management algorithm(rbtree_best_fit with no mutexes)</span>
 461 <span class="comment">//   Name-object mappings are stored in the default index type (flat_map)</span>
 462 <span class="keyword">typedef</span> <span class="identifier">basic_managed_mapped_file</span><span class="special">&lt;</span>
 463    <span class="keyword">wchar_t</span><span class="special">,</span>
 464    <span class="identifier">rbtree_best_fit</span><span class="special">&lt;</span><span class="identifier">mutex_family</span><span class="special">,</span> <span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;,</span>
 465    <span class="identifier">flat_map_index</span>
 466    <span class="special">&gt;</span>  <span class="identifier">wmanaged_mapped_file</span><span class="special">;</span>
 467 </pre>
 468 <p>
 469           <code class="computeroutput"><span class="identifier">managed_mapped_file</span></code> allocates
 470           objects in a memory mapped files associated with a c-string and <code class="computeroutput"><span class="identifier">wmanaged_mapped_file</span></code> allocates objects
 471           in a memory mapped file associated with a wchar_t null terminated string.
 472           Both define the pointer type 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> so they can be used to map the file
 473           at different base addresses in different processes.
 474         </p>
 475 </div>
 476 <div class="section">
 477 <div class="titlepage"><div><div><h4 class="title">
 478 <a name="interprocess.managed_memory_segments.managed_mapped_files.constructing_managed_mapped_files"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_mapped_files.constructing_managed_mapped_files" title="Constructing Managed Mapped Files">Constructing
 479         Managed Mapped Files</a>
 480 </h4></div></div></div>
 481 <p>
 482           Managed mapped file is an advanced class that combines a file and a mapped
 483           region that covers all the file. That means that when we <span class="bold"><strong>create</strong></span>
 484           a new managed mapped file:
 485         </p>
 486 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 487 <li class="listitem">
 488               A new file is created.
 489             </li>
 490 <li class="listitem">
 491               The whole file is mapped in the process' address space.
 492             </li>
 493 <li class="listitem">
 494               Some helper objects are constructed (name-object index, internal synchronization
 495               objects, internal variables...) in the mapped region to implement managed
 496               memory segment features.
 497             </li>
 498 </ul></div>
 499 <p>
 500           When we <span class="bold"><strong>open</strong></span> a managed mapped file
 501         </p>
 502 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 503 <li class="listitem">
 504               A file is opened.
 505             </li>
 506 <li class="listitem">
 507               The whole file is mapped in the process' address space.
 508             </li>
 509 </ul></div>
 510 <p>
 511           To use a managed mapped file, you must include the following header:
 512         </p>
 513 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_mapped_file</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 514 </pre>
 515 <pre class="programlisting"><span class="comment">//1.  Creates a new file</span>
 516 <span class="comment">//    called "MyMappedFile".</span>
 517 <span class="comment">//2.  Maps the whole file to this</span>
 518 <span class="comment">//    process' address space.</span>
 519 <span class="comment">//3.  Constructs some objects in the memory mapped</span>
 520 <span class="comment">//    file to implement managed features.</span>
 521 <span class="comment">//!!  If anything fails, throws interprocess_exception</span>
 522 <span class="comment">//</span>
 523 <span class="identifier">managed_mapped_file</span> <span class="identifier">mfile</span>      <span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span>      <span class="string">"MyMappedFile"</span><span class="special">,</span>   <span class="comment">//Mapped file name      65536);           //Mapped file size</span>
 524 </pre>
 525 <pre class="programlisting"><span class="comment">//1.  Opens a file</span>
 526 <span class="comment">//    called "MyMappedFile".</span>
 527 <span class="comment">//2.  Maps the whole file to this</span>
 528 <span class="comment">//    process' address space.</span>
 529 <span class="comment">//3.  Obtains pointers to constructed internal objects</span>
 530 <span class="comment">//    to implement managed features.</span>
 531 <span class="comment">//!!  If anything fails, throws interprocess_exception</span>
 532 <span class="comment">//</span>
 533 <span class="identifier">managed_mapped_file</span> <span class="identifier">mfile</span>      <span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span>      <span class="string">"MyMappedFile"</span><span class="special">);</span>  <span class="comment">//Mapped file name[c++]</span>
 534
 535 <span class="comment">//1.  If the file was previously created</span>
 536 <span class="comment">//    equivalent to "open_only".</span>
 537 <span class="comment">//2.  Otherwise, equivalent to "open_only" (size is ignored)</span>
 538 <span class="comment">//</span>
 539 <span class="comment">//!!  If anything fails, throws interprocess_exception</span>
 540 <span class="comment">//</span>
 541 <span class="identifier">managed_mapped_file</span> <span class="identifier">mfile</span>      <span class="special">(</span><span class="identifier">open_or_create</span><span class="special">,</span>      <span class="string">"MyMappedFile"</span><span class="special">,</span>   <span class="comment">//Mapped file name      65536);           //Mapped file size</span>
 542 </pre>
 543 <p>
 544           When the <code class="computeroutput"><span class="identifier">managed_mapped_file</span></code>
 545           object is destroyed, the file is automatically unmapped, and all the resources
 546           are freed. To remove the file from the filesystem you could use standard
 547           C <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">remove</span></code> or <span class="bold"><strong>Boost.Filesystem</strong></span>'s
 548           <code class="computeroutput"><span class="identifier">remove</span><span class="special">()</span></code>
 549           functions, but file removing might fail if any process still has the file
 550           mapped in memory or the file is open by any process.
 551         </p>
 552 <p>
 553           To obtain a more portable behaviour, use <code class="computeroutput"><span class="identifier">file_mapping</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*)</span></code>
 554           operation, which will remove the file even if it's being mapped. However,
 555           removal will fail in some OS systems if the file (eg. by C++ file streams)
 556           and no delete share permission was granted to the file. But in most common
 557           cases <code class="computeroutput"><span class="identifier">file_mapping</span><span class="special">::</span><span class="identifier">remove</span></code> is portable enough.
 558         </p>
 559 </div>
 560 <p>
 561         For more information about managed mapped file capabilities, see <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>
 562         class reference.
 563       </p>
 564 </div>
 565 <div class="section">
 566 <div class="titlepage"><div><div><h3 class="title">
 567 <a name="interprocess.managed_memory_segments.managed_memory_segment_features"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features" title="Managed Memory Segment Features">Managed
 568       Memory Segment Features</a>
 569 </h3></div></div></div>
 570 <div class="toc"><dl class="toc">
 571 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.allocate_deallocate">Allocating
 572         fragments of a managed memory segment</a></span></dt>
 573 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.segment_offset">Obtaining
 574         handles to identify data</a></span></dt>
 575 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.allocation_types">Object
 576         construction function family</a></span></dt>
 577 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.anonymous">Anonymous
 578         instance construction</a></span></dt>
 579 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.unique">Unique
 580         instance construction</a></span></dt>
 581 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.synchronization">Synchronization
 582         guarantees</a></span></dt>
 583 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.index_types">Index
 584         types for name/object mappings</a></span></dt>
 585 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_segment_manager">Segment
 586         Manager</a></span></dt>
 587 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_information">Obtaining
 588         information about a constructed object</a></span></dt>
 589 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_atomic_func">Executing
 590         an object function atomically</a></span></dt>
 591 </dl></div>
 592 <p>
 593         The following features are common to all managed memory segment classes,
 594         but we will use managed shared memory in our examples. We can do the same
 595         with memory mapped files or other managed memory segment classes.
 596       </p>
 597 <div class="section">
 598 <div class="titlepage"><div><div><h4 class="title">
 599 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.allocate_deallocate"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.allocate_deallocate" title="Allocating fragments of a managed memory segment">Allocating
 600         fragments of a managed memory segment</a>
 601 </h4></div></div></div>
 602 <p>
 603           If a basic raw-byte allocation is needed from a managed memory segment,
 604           (for example, a managed shared memory), to implement top-level interprocess
 605           communications, this class offers <span class="bold"><strong>allocate</strong></span>
 606           and <span class="bold"><strong>deallocate</strong></span> functions. The allocation
 607           function comes with throwing and no throwing versions. Throwing version
 608           throws boost::interprocess::bad_alloc (which derives from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">bad_alloc</span></code>) if there is no more memory
 609           and the non-throwing version returns 0 pointer.
 610         </p>
 611 <p>
 612 </p>
 613 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 614
 615 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 616 <span class="special">{</span>
 617    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
 618
 619    <span class="comment">//Remove shared memory on construction and destruction</span>
 620    <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
 621    <span class="special">{</span>
 622       <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
 623       <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
 624    <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
 625
 626    <span class="comment">//Managed memory segment that allocates portions of a shared memory</span>
 627    <span class="comment">//segment with the default management algorithm</span>
 628    <span class="identifier">managed_shared_memory</span> <span class="identifier">managed_shm</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span><span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="number">65536</span><span class="special">);</span>
 629
 630    <span class="comment">//Allocate 100 bytes of memory from segment, throwing version</span>
 631    <span class="keyword">void</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">(</span><span class="number">100</span><span class="special">);</span>
 632
 633    <span class="comment">//Deallocate it</span>
 634    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
 635
 636    <span class="comment">//Non throwing version</span>
 637    <span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow</span><span class="special">);</span>
 638
 639    <span class="comment">//Deallocate it</span>
 640    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
 641    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
 642 <span class="special">}</span>
 643 </pre>
 644 <p>
 645         </p>
 646 </div>
 647 <div class="section">
 648 <div class="titlepage"><div><div><h4 class="title">
 649 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.segment_offset"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.segment_offset" title="Obtaining handles to identify data">Obtaining
 650         handles to identify data</a>
 651 </h4></div></div></div>
 652 <p>
 653           The class also offers conversions between absolute addresses that belong
 654           to a managed memory segment and a handle that can be passed using any interprocess
 655           mechanism. That handle can be transformed again to an absolute address
 656           using a managed memory segment that also contains that object. Handles
 657           can be used as keys between processes to identify allocated portions of
 658           a managed memory segment or objects constructed in the managed segment.
 659         </p>
 660 <pre class="programlisting"><span class="comment">//Process A obtains the offset of the address</span>
 661 <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">handle</span> <span class="identifier">handle</span> <span class="special">=</span>
 662    <span class="identifier">segment</span><span class="special">.</span><span class="identifier">get_handle_from_address</span><span class="special">(</span><span class="identifier">processA_address</span><span class="special">);</span>
 663
 664 <span class="comment">//Process A sends this address using any mechanism to process B</span>
 665
 666 <span class="comment">//Process B obtains the handle and transforms it again to an address</span>
 667 <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">handle</span> <span class="identifier">handle</span> <span class="special">=</span> <span class="special">...</span>
 668 <span class="keyword">void</span> <span class="special">*</span> <span class="identifier">processB_address</span> <span class="special">=</span> <span class="identifier">segment</span><span class="special">.</span><span class="identifier">get_address_from_handle</span><span class="special">(</span><span class="identifier">handle</span><span class="special">);</span>
 669 </pre>
 670 </div>
 671 <div class="section">
 672 <div class="titlepage"><div><div><h4 class="title">
 673 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.allocation_types"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.allocation_types" title="Object construction function family">Object
 674         construction function family</a>
 675 </h4></div></div></div>
 676 <p>
 677           When constructing objects in a managed memory segment (managed shared memory,
 678           managed mapped files...) associated with a name, the user has a varied
 679           object construction family to "construct" or to "construct
 680           if not found". <span class="bold"><strong>Boost.Interprocess</strong></span>
 681           can construct a single object or an array of objects. The array can be
 682           constructed with the same parameters for all objects or we can define each
 683           parameter from a list of iterators:
 684         </p>
 685 <pre class="programlisting"><span class="comment">//!Allocates and constructs an object of type MyType (throwing version)</span>
 686 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">)</span> <span class="special">(</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 687
 688 <span class="comment">//!Allocates and constructs an array of objects of type MyType (throwing version)</span>
 689 <span class="comment">//!Each object receives the same parameters (par1, par2, ...)</span>
 690 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">)[</span><span class="identifier">count</span><span class="special">](</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 691
 692 <span class="comment">//!Tries to find a previously created object. If not present, allocates</span>
 693 <span class="comment">//!and constructs an object of type MyType (throwing version)</span>
 694 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">find_or_construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">)</span> <span class="special">(</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 695
 696 <span class="comment">//!Tries to find a previously created object. If not present, allocates and</span>
 697 <span class="comment">//!constructs an array of objects of type MyType (throwing version). Each object</span>
 698 <span class="comment">//!receives the same parameters (par1, par2, ...)</span>
 699 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">find_or_construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">)[</span><span class="identifier">count</span><span class="special">](</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 700
 701 <span class="comment">//!Allocates and constructs an array of objects of type MyType (throwing version)</span>
 702 <span class="comment">//!Each object receives parameters returned with the expression (*it1++, *it2++,... )</span>
 703 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">construct_it</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">)[</span><span class="identifier">count</span><span class="special">](</span><span class="identifier">it1</span><span class="special">,</span> <span class="identifier">it2</span><span class="special">...);</span>
 704
 705 <span class="comment">//!Tries to find a previously created object. If not present, allocates and constructs</span>
 706 <span class="comment">//!an array of objects of type MyType (throwing version).  Each object receives</span>
 707 <span class="comment">//!parameters returned with the expression (*it1++, *it2++,... )</span>
 708 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">find_or_construct_it</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">)[</span><span class="identifier">count</span><span class="special">](</span><span class="identifier">it1</span><span class="special">,</span> <span class="identifier">it2</span><span class="special">...);</span>
 709
 710 <span class="comment">//!Tries to find a previously created object. Returns a pointer to the object and the</span>
 711 <span class="comment">//!count (if it is not an array, returns 1). If not present, the returned pointer is 0</span>
 712 <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">MyType</span> <span class="special">*,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&gt;</span> <span class="identifier">ret</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">);</span>
 713
 714 <span class="comment">//!Destroys the created object, returns false if not present</span>
 715 <span class="keyword">bool</span> <span class="identifier">destroyed</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">destroy</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">);</span>
 716
 717 <span class="comment">//!Destroys the created object via pointer</span>
 718 <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
 719 </pre>
 720 <p>
 721           All these functions have a non-throwing version, that is invoked with an
 722           additional parameter std::nothrow. For example, for simple object construction:
 723         </p>
 724 <pre class="programlisting"><span class="comment">//!Allocates and constructs an object of type MyType (no throwing version)</span>
 725 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow</span><span class="special">)</span> <span class="special">(</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 726 </pre>
 727 </div>
 728 <div class="section">
 729 <div class="titlepage"><div><div><h4 class="title">
 730 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.anonymous"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.anonymous" title="Anonymous instance construction">Anonymous
 731         instance construction</a>
 732 </h4></div></div></div>
 733 <p>
 734           Sometimes, the user doesn't want to create class objects associated with
 735           a name. For this purpose, <span class="bold"><strong>Boost.Interprocess</strong></span>
 736           can create anonymous objects in a managed memory segment. All named object
 737           construction functions are available to construct anonymous objects. To
 738           allocate an anonymous objects, the user must use "boost::interprocess::anonymous_instance"
 739           name instead of a normal name:
 740         </p>
 741 <pre class="programlisting"><span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="identifier">anonymous_instance</span><span class="special">)</span> <span class="special">(</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 742
 743 <span class="comment">//Other construct variants can also be used (including non-throwing ones)</span>
 744 <span class="special">...</span>
 745
 746 <span class="comment">//We can only destroy the anonymous object via pointer</span>
 747 <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
 748 </pre>
 749 <p>
 750           Find functions have no sense here, since anonymous objects have no name.
 751           We can only destroy the anonymous object via pointer.
 752         </p>
 753 </div>
 754 <div class="section">
 755 <div class="titlepage"><div><div><h4 class="title">
 756 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.unique"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.unique" title="Unique instance construction">Unique
 757         instance construction</a>
 758 </h4></div></div></div>
 759 <p>
 760           Sometimes, the user wants to emulate a singleton in a managed memory segment.
 761           Obviously, as the managed memory segment is constructed at run-time, the
 762           user must construct and destroy this object explicitly. But how can the
 763           user be sure that the object is the only object of its type in the managed
 764           memory segment? This can be emulated using a named object and checking
 765           if it is present before trying to create one, but all processes must agree
 766           in the object's name, that can also conflict with other existing names.
 767         </p>
 768 <p>
 769           To solve this, <span class="bold"><strong>Boost.Interprocess</strong></span> offers
 770           a "unique object" creation in a managed memory segment. Only
 771           one instance of a class can be created in a managed memory segment using
 772           this "unique object" service (you can create more named objects
 773           of this class, though) so it makes easier the emulation of singleton-like
 774           objects across processes, for example, to design pooled, shared memory
 775           allocators. The object can be searched using the type of the class as a
 776           key.
 777         </p>
 778 <pre class="programlisting"><span class="comment">// Construct</span>
 779 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="identifier">unique_instance</span><span class="special">)</span> <span class="special">(</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 780
 781 <span class="comment">// Find it</span>
 782 <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">MyType</span> <span class="special">*,</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&gt;</span> <span class="identifier">ret</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="identifier">unique_instance</span><span class="special">);</span>
 783
 784 <span class="comment">// Destroy it</span>
 785 <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">destroy</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="identifier">unique_instance</span><span class="special">);</span>
 786
 787 <span class="comment">// Other construct and find variants can also be used (including non-throwing ones)</span>
 788 <span class="comment">//...</span>
 789 </pre>
 790 <pre class="programlisting"><span class="comment">// We can also destroy the unique object via pointer</span>
 791 <span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_memory_segment</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="identifier">unique_instance</span><span class="special">)</span> <span class="special">(</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 792 <span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
 793 </pre>
 794 <p>
 795           The find function obtains a pointer to the only object of type T that can
 796           be created using this "unique instance" mechanism.
 797         </p>
 798 </div>
 799 <div class="section">
 800 <div class="titlepage"><div><div><h4 class="title">
 801 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.synchronization"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.synchronization" title="Synchronization guarantees">Synchronization
 802         guarantees</a>
 803 </h4></div></div></div>
 804 <p>
 805           One of the features of named/unique allocations/searches/destructions is
 806           that they are <span class="bold"><strong>atomic</strong></span>. Named allocations
 807           use the recursive synchronization scheme defined by the internal <code class="computeroutput"><span class="identifier">mutex_family</span></code> typedef defined of the memory
 808           allocation algorithm template parameter (<code class="computeroutput"><span class="identifier">MemoryAlgorithm</span></code>).
 809           That is, the mutex type used to synchronize named/unique allocations is
 810           defined by the <code class="computeroutput"><span class="identifier">MemoryAlgorithm</span><span class="special">::</span><span class="identifier">mutex_family</span><span class="special">::</span><span class="identifier">recursive_mutex_type</span></code>
 811           type. For shared memory, and memory mapped file based managed segments
 812           this recursive mutex is defined as <code class="computeroutput"><a class="link" href="../boost/interprocess/interprocess_r_idp66640512.html" title="Class interprocess_recursive_mutex">interprocess_recursive_mutex</a></code>.
 813         </p>
 814 <p>
 815           If two processes can call:
 816         </p>
 817 <pre class="programlisting"><span class="identifier">MyType</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">find_or_construct</span><span class="special">&lt;</span><span class="identifier">MyType</span><span class="special">&gt;(</span><span class="string">"Name"</span><span class="special">)[</span><span class="identifier">count</span><span class="special">](</span><span class="identifier">par1</span><span class="special">,</span> <span class="identifier">par2</span><span class="special">...);</span>
 818 </pre>
 819 <p>
 820           at the same time, but only one process will create the object and the other
 821           will obtain a pointer to the created object.
 822         </p>
 823 <p>
 824           Raw allocation using <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> can be called also safely while executing
 825           named/anonymous/unique allocations, just like when programming a multithreaded
 826           application inserting an object in a mutex-protected map does not block
 827           other threads from calling new[] while the map thread is searching the
 828           place where it has to insert the new object. The synchronization does happen
 829           once the map finds the correct place and it has to allocate raw memory
 830           to construct the new value.
 831         </p>
 832 <p>
 833           This means that if we are creating or searching for a lot of named objects,
 834           we only block creation/searches from other processes but we don't block
 835           another process if that process is inserting elements in a shared memory
 836           vector.
 837         </p>
 838 </div>
 839 <div class="section">
 840 <div class="titlepage"><div><div><h4 class="title">
 841 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.index_types"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.index_types" title="Index types for name/object mappings">Index
 842         types for name/object mappings</a>
 843 </h4></div></div></div>
 844 <p>
 845           As seen, managed memory segments, when creating named objects, store the
 846           name/object association in an index. The index is a map with the name of
 847           the object as a key and a pointer to the object as the mapped type. The
 848           default specializations, <span class="bold"><strong>managed_shared_memory</strong></span>
 849           and <span class="bold"><strong>wmanaged_shared_memory</strong></span>, use <span class="bold"><strong>flat_map_index</strong></span> as the index type.
 850         </p>
 851 <p>
 852           Each index has its own characteristics, like search-time, insertion time,
 853           deletion time, memory use, and memory allocation patterns. <span class="bold"><strong>Boost.Interprocess</strong></span>
 854           offers 3 index types right now:
 855         </p>
 856 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 857 <li class="listitem">
 858               <span class="bold"><strong>boost::interprocess::flat_map_index flat_map_index</strong></span>:
 859               Based on boost::interprocess::flat_map, an ordered vector similar to
 860               Loki library's AssocVector class, offers great search time and minimum
 861               memory use. But the vector must be reallocated when is full, so all
 862               data must be copied to the new buffer. Ideal when insertions are mainly
 863               in initialization time and in run-time we just need searches.
 864             </li>
 865 <li class="listitem">
 866               <span class="bold"><strong>boost::interprocess::map_index map_index</strong></span>:
 867               Based on boost::interprocess::map, a managed memory ready version of
 868               std::map. Since it's a node based container, it has no reallocations,
 869               the tree must be just rebalanced sometimes. Offers equilibrated insertion/deletion/search
 870               times with more overhead per node comparing to <span class="bold"><strong>boost::interprocess::flat_map_index</strong></span>.
 871               Ideal when searches/insertions/deletions are in random order.
 872             </li>
 873 <li class="listitem">
 874               <span class="bold"><strong>boost::interprocess::null_index null_index</strong></span>:
 875               This index is for people using a managed memory segment just for raw
 876               memory buffer allocations and they don't make use of named/unique allocations.
 877               This class is just empty and saves some space and compilation time.
 878               If you try to use named object creation with a managed memory segment
 879               using this index, you will get a compilation error.
 880             </li>
 881 </ul></div>
 882 <p>
 883           As an example, if we want to define new managed shared memory class using
 884           <span class="bold"><strong>boost::interprocess::map</strong></span> as the index
 885           type we just must specify [boost::interprocess::map_index map_index] as
 886           a template parameter:
 887         </p>
 888 <pre class="programlisting"><span class="comment">//This managed memory segment can allocate objects with:</span>
 889 <span class="comment">// -&gt; a wchar_t string as key</span>
 890 <span class="comment">// -&gt; boost::interprocess::rbtree_best_fit with process-shared mutexes</span>
 891 <span class="comment">//       as memory allocation algorithm.</span>
 892 <span class="comment">// -&gt; boost::interprocess::map&lt;...&gt; as the index to store name/object mappings</span>
 893 <span class="comment">//</span>
 894 <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">basic_managed_shared_memory</span>
 895          <span class="special">&lt;</span>  <span class="keyword">wchar_t</span>
 896          <span class="special">,</span>  <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">rbtree_best_fit</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">mutex_family</span><span class="special">,</span> <span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;</span>
 897          <span class="special">,</span>  <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">map_index</span>
 898          <span class="special">&gt;</span>  <span class="identifier">my_managed_shared_memory</span><span class="special">;</span>
 899 </pre>
 900 <p>
 901           <span class="bold"><strong>Boost.Interprocess</strong></span> plans to offer an
 902           <span class="bold"><strong>unordered_map</strong></span> based index as soon as this
 903           container is included in Boost. If these indexes are not enough for you,
 904           you can define your own index type. To know how to do this, go to <a class="link" href="customizing_interprocess.html#interprocess.customizing_interprocess.custom_indexes" title="Building custom indexes">Building
 905           custom indexes</a> section.
 906         </p>
 907 </div>
 908 <div class="section">
 909 <div class="titlepage"><div><div><h4 class="title">
 910 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_segment_manager"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_segment_manager" title="Segment Manager">Segment
 911         Manager</a>
 912 </h4></div></div></div>
 913 <p>
 914           All <span class="bold"><strong>Boost.Interprocess</strong></span> managed memory
 915           segment classes construct in their respective memory segments (shared memory,
 916           memory mapped files, heap memory...) some structures to implement the memory
 917           management algorithm, named allocations, synchronization objects... All
 918           these objects are encapsulated in a single object called <span class="bold"><strong>segment
 919           manager</strong></span>. A managed memory mapped file and a managed shared memory
 920           use the same <span class="bold"><strong>segment manager</strong></span> to implement
 921           all managed memory segment features, due to the fact that a <span class="bold"><strong>segment
 922           manager</strong></span> is a class that manages a fixed size memory buffer.
 923           Since both shared memory or memory mapped files are accessed though a mapped
 924           region, and a mapped region is a fixed size memory buffer, a single <span class="bold"><strong>segment manager</strong></span> class can manage several managed
 925           memory segment types.
 926         </p>
 927 <p>
 928           Some <span class="bold"><strong>Boost.Interprocess</strong></span> classes require
 929           a pointer to the segment manager in their constructors, and the segment
 930           manager can be obtained from any managed memory segment using <code class="computeroutput"><span class="identifier">get_segment_manager</span></code> member:
 931         </p>
 932 <pre class="programlisting"><span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">segment_manager</span> <span class="special">*</span><span class="identifier">seg_manager</span> <span class="special">=</span>
 933    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">();</span>
 934 </pre>
 935 </div>
 936 <div class="section">
 937 <div class="titlepage"><div><div><h4 class="title">
 938 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_information"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_information" title="Obtaining information about a constructed object">Obtaining
 939         information about a constructed object</a>
 940 </h4></div></div></div>
 941 <p>
 942           Once an object is constructed using <code class="computeroutput"><span class="identifier">construct</span><span class="special">&lt;&gt;</span></code> function family, the programmer
 943           can obtain information about the object using a pointer to the object.
 944           The programmer can obtain the following information:
 945         </p>
 946 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 947 <li class="listitem">
 948               Name of the object: If it's a named instance, the name used in the
 949               construction function is returned, otherwise 0 is returned.
 950             </li>
 951 <li class="listitem">
 952               Length of the object: Returns the number of elements of the object
 953               (1 if it's a single value, &gt;=1 if it's an array).
 954             </li>
 955 <li class="listitem">
 956               The type of construction: Whether the object was constructed using
 957               a named, unique or anonymous construction.
 958             </li>
 959 </ul></div>
 960 <p>
 961           Here is an example showing this functionality:
 962         </p>
 963 <p>
 964 </p>
 965 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 966 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
 967 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstring</span><span class="special">&gt;</span>
 968
 969 <span class="keyword">class</span> <span class="identifier">my_class</span>
 970 <span class="special">{</span>
 971    <span class="comment">//...</span>
 972 <span class="special">};</span>
 973
 974 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
 975 <span class="special">{</span>
 976    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
 977
 978    <span class="comment">//Remove shared memory on construction and destruction</span>
 979    <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
 980    <span class="special">{</span>
 981       <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
 982       <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
 983    <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
 984
 985    <span class="identifier">managed_shared_memory</span> <span class="identifier">managed_shm</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="number">10000</span><span class="special">*</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">));</span>
 986
 987    <span class="comment">//Construct objects</span>
 988    <span class="identifier">my_class</span> <span class="special">*</span><span class="identifier">named_object</span>  <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">my_class</span><span class="special">&gt;(</span><span class="string">"Object name"</span><span class="special">)[</span><span class="number">1</span><span class="special">]();</span>
 989    <span class="identifier">my_class</span> <span class="special">*</span><span class="identifier">unique_object</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">my_class</span><span class="special">&gt;(</span><span class="identifier">unique_instance</span><span class="special">)[</span><span class="number">2</span><span class="special">]();</span>
 990    <span class="identifier">my_class</span> <span class="special">*</span><span class="identifier">anon_object</span>   <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">my_class</span><span class="special">&gt;(</span><span class="identifier">anonymous_instance</span><span class="special">)[</span><span class="number">3</span><span class="special">]();</span>
 991
 992    <span class="comment">//Now test "get_instance_name" function.</span>
 993    <span class="identifier">assert</span><span class="special">(</span><span class="number">0</span> <span class="special">==</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_name</span><span class="special">(</span><span class="identifier">named_object</span><span class="special">),</span> <span class="string">"Object name"</span><span class="special">));</span>
 994    <span class="identifier">assert</span><span class="special">(</span><span class="number">0</span> <span class="special">==</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">strcmp</span><span class="special">(</span><span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_name</span><span class="special">(</span><span class="identifier">unique_object</span><span class="special">),</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">my_class</span><span class="special">).</span><span class="identifier">name</span><span class="special">()));</span>
 995    <span class="identifier">assert</span><span class="special">(</span><span class="number">0</span> <span class="special">==</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_name</span><span class="special">(</span><span class="identifier">anon_object</span><span class="special">));</span>
 996
 997    <span class="comment">//Now test "get_instance_type" function.</span>
 998    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">named_type</span>     <span class="special">==</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_type</span><span class="special">(</span><span class="identifier">named_object</span><span class="special">));</span>
 999    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">unique_type</span>    <span class="special">==</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_type</span><span class="special">(</span><span class="identifier">unique_object</span><span class="special">));</span>
1000    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">anonymous_type</span> <span class="special">==</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_type</span><span class="special">(</span><span class="identifier">anon_object</span><span class="special">));</span>
1001
1002    <span class="comment">//Now test "get_instance_length" function.</span>
1003    <span class="identifier">assert</span><span class="special">(</span><span class="number">1</span> <span class="special">==</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_length</span><span class="special">(</span><span class="identifier">named_object</span><span class="special">));</span>
1004    <span class="identifier">assert</span><span class="special">(</span><span class="number">2</span> <span class="special">==</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_length</span><span class="special">(</span><span class="identifier">unique_object</span><span class="special">));</span>
1005    <span class="identifier">assert</span><span class="special">(</span><span class="number">3</span> <span class="special">==</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">get_instance_length</span><span class="special">(</span><span class="identifier">anon_object</span><span class="special">));</span>
1006
1007    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">named_object</span><span class="special">);</span>
1008    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">unique_object</span><span class="special">);</span>
1009    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">anon_object</span><span class="special">);</span>
1010    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1011 <span class="special">}</span>
1012 </pre>
1013 <p>
1014         </p>
1015 </div>
1016 <div class="section">
1017 <div class="titlepage"><div><div><h4 class="title">
1018 <a name="interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_atomic_func"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_features.managed_memory_segment_atomic_func" title="Executing an object function atomically">Executing
1019         an object function atomically</a>
1020 </h4></div></div></div>
1021 <p>
1022           Sometimes the programmer must execute some code, and needs to execute it
1023           with the guarantee that no other process or thread will create or destroy
1024           any named, unique or anonymous object while executing the functor. A user
1025           might want to create several named objects and initialize them, but those
1026           objects should be available for the rest of processes at once.
1027         </p>
1028 <p>
1029           To achieve this, the programmer can use the <code class="computeroutput"><span class="identifier">atomic_func</span><span class="special">()</span></code> function offered by managed classes:
1030         </p>
1031 <pre class="programlisting"><span class="comment">//This object function will create several named objects</span>
1032 <span class="identifier">create_several_objects_func</span> <span class="identifier">func</span><span class="special">(/**/);</span>
1033
1034 <span class="comment">//While executing the function, no other process will be</span>
1035 <span class="comment">//able to create or destroy objects</span>
1036 <span class="identifier">managed_memory</span><span class="special">.</span><span class="identifier">atomic_func</span><span class="special">(</span><span class="identifier">func</span><span class="special">);</span>
1037 </pre>
1038 <p>
1039           Note that <code class="computeroutput"><span class="identifier">atomic_func</span></code> does
1040           not prevent other processes from allocating raw memory or executing member
1041           functions for already constructed objects (e.g.: another process might
1042           be pushing elements into a vector placed in the segment). The atomic function
1043           only blocks named, unique and anonymous creation, search and destruction
1044           (concurrent calls to <code class="computeroutput"><span class="identifier">construct</span><span class="special">&lt;&gt;</span></code>, <code class="computeroutput"><span class="identifier">find</span><span class="special">&lt;&gt;</span></code>, <code class="computeroutput"><span class="identifier">find_or_construct</span><span class="special">&lt;&gt;</span></code>, <code class="computeroutput"><span class="identifier">destroy</span><span class="special">&lt;&gt;</span></code>...) from other processes.
1045         </p>
1046 </div>
1047 </div>
1048 <div class="section">
1049 <div class="titlepage"><div><div><h3 class="title">
1050 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features" title="Managed Memory Segment Advanced Features">Managed
1051       Memory Segment Advanced Features</a>
1052 </h3></div></div></div>
1053 <div class="toc"><dl class="toc">
1054 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_information">Obtaining
1055         information about the managed segment</a></span></dt>
1056 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.growing_managed_memory">Growing
1057         managed segments</a></span></dt>
1058 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_advanced_index_functions">Advanced
1059         index functions</a></span></dt>
1060 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.allocate_aligned">Allocating
1061         aligned memory portions</a></span></dt>
1062 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_multiple_allocations">Multiple
1063         allocation functions</a></span></dt>
1064 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_expand_in_place">Expand
1065         in place memory allocation</a></span></dt>
1066 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.copy_on_write_read_only">Opening
1067         managed shared memory and mapped files with Copy On Write or Read Only modes</a></span></dt>
1068 </dl></div>
1069 <div class="section">
1070 <div class="titlepage"><div><div><h4 class="title">
1071 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_information"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_information" title="Obtaining information about the managed segment">Obtaining
1072         information about the managed segment</a>
1073 </h4></div></div></div>
1074 <p>
1075           These functions are available to obtain information about the managed memory
1076           segments:
1077         </p>
1078 <p>
1079           Obtain the size of the memory segment:
1080         </p>
1081 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_size</span><span class="special">();</span>
1082 </pre>
1083 <p>
1084           Obtain the number of free bytes of the segment:
1085         </p>
1086 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_free_memory</span><span class="special">();</span>
1087 </pre>
1088 <p>
1089           Clear to zero the free memory:
1090         </p>
1091 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">zero_free_memory</span><span class="special">();</span>
1092 </pre>
1093 <p>
1094           Know if all memory has been deallocated, false otherwise:
1095         </p>
1096 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">all_memory_deallocated</span><span class="special">();</span>
1097 </pre>
1098 <p>
1099           Test internal structures of the managed segment. Returns true if no errors
1100           are detected:
1101         </p>
1102 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">check_sanity</span><span class="special">();</span>
1103 </pre>
1104 <p>
1105           Obtain the number of named and unique objects allocated in the segment:
1106         </p>
1107 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_num_named_objects</span><span class="special">();</span>
1108 <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_num_unique_objects</span><span class="special">();</span>
1109 </pre>
1110 </div>
1111 <div class="section">
1112 <div class="titlepage"><div><div><h4 class="title">
1113 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features.growing_managed_memory"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.growing_managed_memory" title="Growing managed segments">Growing
1114         managed segments</a>
1115 </h4></div></div></div>
1116 <p>
1117           Once a managed segment is created the managed segment can't be grown. The
1118           limitation is not easily solvable: every process attached to the managed
1119           segment would need to be stopped, notified of the new size, they would
1120           need to remap the managed segment and continue working. Nearly impossible
1121           to achieve with a user-level library without the help of the operating
1122           system kernel.
1123         </p>
1124 <p>
1125           On the other hand, <span class="bold"><strong>Boost.Interprocess</strong></span>
1126           offers off-line segment growing. What does this mean? That the segment
1127           can be grown if no process has mapped the managed segment. If the application
1128           can find a moment where no process is attached it can grow or shrink to
1129           fit the managed segment.
1130         </p>
1131 <p>
1132           Here we have an example showing how to grow and shrink to fit <code class="computeroutput"><a class="link" href="../boost/interprocess/managed_shared_memory.html" title="Type definition managed_shared_memory">managed_shared_memory</a></code>:
1133         </p>
1134 <p>
1135 </p>
1136 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
1137 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_mapped_file</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
1138 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
1139
1140 <span class="keyword">class</span> <span class="identifier">MyClass</span>
1141 <span class="special">{</span>
1142    <span class="comment">//...</span>
1143 <span class="special">};</span>
1144
1145 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1146 <span class="special">{</span>
1147    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
1148    <span class="comment">//Remove shared memory on construction and destruction</span>
1149    <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
1150    <span class="special">{</span>
1151       <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1152       <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1153    <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
1154
1155    <span class="special">{</span>
1156       <span class="comment">//Create a managed shared memory</span>
1157       <span class="identifier">managed_shared_memory</span> <span class="identifier">shm</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="number">1000</span><span class="special">);</span>
1158
1159       <span class="comment">//Check size</span>
1160       <span class="identifier">assert</span><span class="special">(</span><span class="identifier">shm</span><span class="special">.</span><span class="identifier">get_size</span><span class="special">()</span> <span class="special">==</span> <span class="number">1000</span><span class="special">);</span>
1161       <span class="comment">//Construct a named object</span>
1162       <span class="identifier">MyClass</span> <span class="special">*</span><span class="identifier">myclass</span> <span class="special">=</span> <span class="identifier">shm</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyClass</span><span class="special">&gt;(</span><span class="string">"MyClass"</span><span class="special">)();</span>
1163       <span class="comment">//The managed segment is unmapped here</span>
1164    <span class="special">}</span>
1165    <span class="special">{</span>
1166       <span class="comment">//Now that the segment is not mapped grow it adding extra 500 bytes</span>
1167       <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">grow</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="number">500</span><span class="special">);</span>
1168
1169       <span class="comment">//Map it again</span>
1170       <span class="identifier">managed_shared_memory</span> <span class="identifier">shm</span><span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span> <span class="string">"MySharedMemory"</span><span class="special">);</span>
1171       <span class="comment">//Check size</span>
1172       <span class="identifier">assert</span><span class="special">(</span><span class="identifier">shm</span><span class="special">.</span><span class="identifier">get_size</span><span class="special">()</span> <span class="special">==</span> <span class="number">1500</span><span class="special">);</span>
1173       <span class="comment">//Check "MyClass" is still there</span>
1174       <span class="identifier">MyClass</span> <span class="special">*</span><span class="identifier">myclass</span> <span class="special">=</span> <span class="identifier">shm</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="identifier">MyClass</span><span class="special">&gt;(</span><span class="string">"MyClass"</span><span class="special">).</span><span class="identifier">first</span><span class="special">;</span>
1175       <span class="identifier">assert</span><span class="special">(</span><span class="identifier">myclass</span> <span class="special">!=</span> <span class="number">0</span><span class="special">);</span>
1176       <span class="comment">//The managed segment is unmapped here</span>
1177    <span class="special">}</span>
1178    <span class="special">{</span>
1179       <span class="comment">//Now minimize the size of the segment</span>
1180       <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">shrink_to_fit</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span>
1181
1182       <span class="comment">//Map it again</span>
1183       <span class="identifier">managed_shared_memory</span> <span class="identifier">shm</span><span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span> <span class="string">"MySharedMemory"</span><span class="special">);</span>
1184       <span class="comment">//Check size</span>
1185       <span class="identifier">assert</span><span class="special">(</span><span class="identifier">shm</span><span class="special">.</span><span class="identifier">get_size</span><span class="special">()</span> <span class="special">&lt;</span> <span class="number">1000</span><span class="special">);</span>
1186       <span class="comment">//Check "MyClass" is still there</span>
1187       <span class="identifier">MyClass</span> <span class="special">*</span><span class="identifier">myclass</span> <span class="special">=</span> <span class="identifier">shm</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="identifier">MyClass</span><span class="special">&gt;(</span><span class="string">"MyClass"</span><span class="special">).</span><span class="identifier">first</span><span class="special">;</span>
1188       <span class="identifier">assert</span><span class="special">(</span><span class="identifier">myclass</span> <span class="special">!=</span> <span class="number">0</span><span class="special">);</span>
1189       <span class="comment">//The managed segment is unmapped here</span>
1190    <span class="special">}</span>
1191    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1192 <span class="special">}</span>
1193 </pre>
1194 <p>
1195         </p>
1196 <p>
1197           <code class="computeroutput"><a class="link" href="../boost/interprocess/managed_mapped_file.html" title="Type definition managed_mapped_file">managed_mapped_file</a></code>
1198           also offers a similar function to grow or shrink_to_fit the managed file.
1199           Please, remember that <span class="bold"><strong>no process should be modifying
1200           the file/shared memory while the growing/shrinking process is performed</strong></span>.
1201           Otherwise, the managed segment will be corrupted.
1202         </p>
1203 </div>
1204 <div class="section">
1205 <div class="titlepage"><div><div><h4 class="title">
1206 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_advanced_index_functions"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_advanced_index_functions" title="Advanced index functions">Advanced
1207         index functions</a>
1208 </h4></div></div></div>
1209 <p>
1210           As mentioned, the managed segment stores the information about named and
1211           unique objects in two indexes. Depending on the type of those indexes,
1212           the index must reallocate some auxiliary structures when new named or unique
1213           allocations are made. For some indexes, if the user knows how many named
1214           or unique objects are going to be created it's possible to preallocate
1215           some structures to obtain much better performance. (If the index is an
1216           ordered vector it can preallocate memory to avoid reallocations. If the
1217           index is a hash structure it can preallocate the bucket array).
1218         </p>
1219 <p>
1220           The following functions reserve memory to make the subsequent allocation
1221           of named or unique objects more efficient. These functions are only useful
1222           for pseudo-intrusive or non-node indexes (like <code class="computeroutput"><span class="identifier">flat_map_index</span></code>,
1223           <code class="computeroutput"><span class="identifier">iunordered_set_index</span></code>).
1224           These functions have no effect with the default index (<code class="computeroutput"><span class="identifier">iset_index</span></code>)
1225           or other indexes (<code class="computeroutput"><span class="identifier">map_index</span></code>):
1226         </p>
1227 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">reserve_named_objects</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span>
1228 <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">reserve_unique_objects</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span>
1229 </pre>
1230 <pre class="programlisting"><span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">reserve_named_objects</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span>
1231 <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">reserve_unique_objects</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span>
1232 </pre>
1233 <p>
1234           Managed memory segments also offer the possibility to iterate through constructed
1235           named and unique objects for debugging purposes. <span class="bold"><strong>Caution:
1236           this iteration is not thread-safe</strong></span> so the user should make sure
1237           that no other thread is manipulating named or unique indexes (creating,
1238           erasing, reserving...) in the segment. Other operations not involving indexes
1239           can be concurrently executed (raw memory allocation/deallocations, for
1240           example).
1241         </p>
1242 <p>
1243           The following functions return constant iterators to the range of named
1244           and unique objects stored in the managed segment. Depending on the index
1245           type, iterators might be invalidated after a named or unique creation/erasure/reserve
1246           operation:
1247         </p>
1248 <pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">const_named_iterator</span> <span class="identifier">const_named_it</span><span class="special">;</span>
1249 <span class="identifier">const_named_it</span> <span class="identifier">named_beg</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">named_begin</span><span class="special">();</span>
1250 <span class="identifier">const_named_it</span> <span class="identifier">named_end</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">named_end</span><span class="special">();</span>
1251
1252 <span class="keyword">typedef</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">const_unique_iterator</span> <span class="identifier">const_unique_it</span><span class="special">;</span>
1253 <span class="identifier">const_unique_it</span> <span class="identifier">unique_beg</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">unique_begin</span><span class="special">();</span>
1254 <span class="identifier">const_unique_it</span> <span class="identifier">unique_end</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">unique_end</span><span class="special">();</span>
1255
1256 <span class="keyword">for</span><span class="special">(;</span> <span class="identifier">named_beg</span> <span class="special">!=</span> <span class="identifier">named_end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">named_beg</span><span class="special">){</span>
1257    <span class="comment">//A pointer to the name of the named object</span>
1258    <span class="keyword">const</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">char_type</span> <span class="special">*</span><span class="identifier">name</span> <span class="special">=</span> <span class="identifier">named_beg</span><span class="special">-&gt;</span><span class="identifier">name</span><span class="special">();</span>
1259    <span class="comment">//The length of the name</span>
1260    <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">name_len</span> <span class="special">=</span> <span class="identifier">named_beg</span><span class="special">-&gt;</span><span class="identifier">name_length</span><span class="special">();</span>
1261    <span class="comment">//A constant void pointer to the named object</span>
1262    <span class="keyword">const</span> <span class="keyword">void</span> <span class="special">*</span><span class="identifier">value</span> <span class="special">=</span> <span class="identifier">named_beg</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">();</span>
1263 <span class="special">}</span>
1264
1265 <span class="keyword">for</span><span class="special">(;</span> <span class="identifier">unique_beg</span> <span class="special">!=</span> <span class="identifier">unique_end</span><span class="special">;</span> <span class="special">++</span><span class="identifier">unique_beg</span><span class="special">){</span>
1266    <span class="comment">//The typeid(T).name() of the unique object</span>
1267    <span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span><span class="identifier">typeid_name</span> <span class="special">=</span> <span class="identifier">unique_beg</span><span class="special">-&gt;</span><span class="identifier">name</span><span class="special">();</span>
1268    <span class="comment">//The length of the name</span>
1269    <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">name_len</span> <span class="special">=</span> <span class="identifier">unique_beg</span><span class="special">-&gt;</span><span class="identifier">name_length</span><span class="special">();</span>
1270    <span class="comment">//A constant void pointer to the unique object</span>
1271    <span class="keyword">const</span> <span class="keyword">void</span> <span class="special">*</span><span class="identifier">value</span> <span class="special">=</span> <span class="identifier">unique_beg</span><span class="special">-&gt;</span><span class="identifier">value</span><span class="special">();</span>
1272 <span class="special">}</span>
1273 </pre>
1274 </div>
1275 <div class="section">
1276 <div class="titlepage"><div><div><h4 class="title">
1277 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features.allocate_aligned"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.allocate_aligned" title="Allocating aligned memory portions">Allocating
1278         aligned memory portions</a>
1279 </h4></div></div></div>
1280 <p>
1281           Sometimes it's interesting to be able to allocate aligned fragments of
1282           memory because of some hardware or software restrictions. Sometimes, having
1283           aligned memory is a feature that can be used to improve several memory
1284           algorithms.
1285         </p>
1286 <p>
1287           This allocation is similar to the previously shown raw memory allocation
1288           but it takes an additional parameter specifying the alignment. There is
1289           a restriction for the alignment: <span class="bold"><strong>the alignment must
1290           be power of two</strong></span>.
1291         </p>
1292 <p>
1293           If a user wants to allocate many aligned blocks (for example aligned to
1294           128 bytes), the size that minimizes the memory waste is a value that's
1295           is nearly a multiple of that alignment (for example 2*128 - some bytes).
1296           The reason for this is that every memory allocation usually needs some
1297           additional metadata in the first bytes of the allocated buffer. If the
1298           user can know the value of "some bytes" and if the first bytes
1299           of a free block of memory are used to fulfill the aligned allocation, the
1300           rest of the block can be left also aligned and ready for the next aligned
1301           allocation. Note that requesting <span class="bold"><strong>a size multiple
1302           of the alignment is not optimal</strong></span> because lefts the next block
1303           of memory unaligned due to the needed metadata.
1304         </p>
1305 <p>
1306           Once the programmer knows the size of the payload of every memory allocation,
1307           he can request a size that will be optimal to allocate aligned chunks of
1308           memory maximizing both the size of the request <span class="bold"><strong>and</strong></span>
1309           the possibilities of future aligned allocations. This information is stored
1310           in the PayloadPerAllocation constant of managed memory segments.
1311         </p>
1312 <p>
1313           Here is a small example showing how aligned allocation is used:
1314         </p>
1315 <p>
1316 </p>
1317 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
1318 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
1319
1320 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1321 <span class="special">{</span>
1322    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
1323
1324    <span class="comment">//Remove shared memory on construction and destruction</span>
1325    <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
1326    <span class="special">{</span>
1327       <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1328       <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1329    <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
1330
1331    <span class="comment">//Managed memory segment that allocates portions of a shared memory</span>
1332    <span class="comment">//segment with the default management algorithm</span>
1333    <span class="identifier">managed_shared_memory</span> <span class="identifier">managed_shm</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="number">65536</span><span class="special">);</span>
1334
1335    <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">Alignment</span> <span class="special">=</span> <span class="number">128</span><span class="special">;</span>
1336
1337    <span class="comment">//Allocate 100 bytes aligned to Alignment from segment, throwing version</span>
1338    <span class="keyword">void</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocate_aligned</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="identifier">Alignment</span><span class="special">);</span>
1339
1340    <span class="comment">//Check alignment</span>
1341    <span class="identifier">assert</span><span class="special">((</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="identifier">ptr</span><span class="special">)-</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="number">0</span><span class="special">))</span> <span class="special">%</span> <span class="identifier">Alignment</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
1342
1343    <span class="comment">//Deallocate it</span>
1344    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
1345
1346    <span class="comment">//Non throwing version</span>
1347    <span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocate_aligned</span><span class="special">(</span><span class="number">100</span><span class="special">,</span> <span class="identifier">Alignment</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow</span><span class="special">);</span>
1348
1349    <span class="comment">//Check alignment</span>
1350    <span class="identifier">assert</span><span class="special">((</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="identifier">ptr</span><span class="special">)-</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="number">0</span><span class="special">))</span> <span class="special">%</span> <span class="identifier">Alignment</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
1351
1352    <span class="comment">//Deallocate it</span>
1353    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
1354
1355    <span class="comment">//If we want to efficiently allocate aligned blocks of memory</span>
1356    <span class="comment">//use managed_shared_memory::PayloadPerAllocation value</span>
1357    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">Alignment</span> <span class="special">&gt;</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">PayloadPerAllocation</span><span class="special">);</span>
1358
1359    <span class="comment">//This allocation will maximize the size of the aligned memory</span>
1360    <span class="comment">//and will increase the possibility of finding more aligned memory</span>
1361    <span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocate_aligned</span>
1362       <span class="special">(</span><span class="number">3</span><span class="special">*</span><span class="identifier">Alignment</span> <span class="special">-</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">PayloadPerAllocation</span><span class="special">,</span> <span class="identifier">Alignment</span><span class="special">);</span>
1363
1364    <span class="comment">//Check alignment</span>
1365    <span class="identifier">assert</span><span class="special">((</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="identifier">ptr</span><span class="special">)-</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="number">0</span><span class="special">))</span> <span class="special">%</span> <span class="identifier">Alignment</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span>
1366
1367    <span class="comment">//Deallocate it</span>
1368    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
1369
1370    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1371 <span class="special">}</span>
1372 </pre>
1373 <p>
1374         </p>
1375 </div>
1376 <div class="section">
1377 <div class="titlepage"><div><div><h4 class="title">
1378 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_multiple_allocations"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_multiple_allocations" title="Multiple allocation functions">Multiple
1379         allocation functions</a>
1380 </h4></div></div></div>
1381 <div class="caution"><table border="0" summary="Caution">
1382 <tr>
1383 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../doc/src/images/caution.png"></td>
1384 <th align="left">Caution</th>
1385 </tr>
1386 <tr><td align="left" valign="top"><p>
1387             This feature is experimental, interface and ABI are unstable
1388           </p></td></tr>
1389 </table></div>
1390 <p>
1391           If an application needs to allocate a lot of memory buffers but it needs
1392           to deallocate them independently, the application is normally forced to
1393           loop calling <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code>.
1394           Managed memory segments offer an alternative function to pack several allocations
1395           in a single call obtaining memory buffers that:
1396         </p>
1397 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1398 <li class="listitem">
1399               are packed contiguously in memory (which improves locality)
1400             </li>
1401 <li class="listitem">
1402               can be independently deallocated.
1403             </li>
1404 </ul></div>
1405 <p>
1406           This allocation method is much faster than calling <code class="computeroutput"><span class="identifier">allocate</span><span class="special">()</span></code> in a loop. The downside is that the segment
1407           must provide a contiguous memory segment big enough to hold all the allocations.
1408           Managed memory segments offer this functionality through <code class="computeroutput"><span class="identifier">allocate_many</span><span class="special">()</span></code>
1409           functions. There are 2 types of <code class="computeroutput"><span class="identifier">allocate_many</span></code>
1410           functions:
1411         </p>
1412 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1413 <li class="listitem">
1414               Allocation of N buffers of memory with the same size.
1415             </li>
1416 <li class="listitem">
1417               Allocation ot N buffers of memory, each one of different size.
1418             </li>
1419 </ul></div>
1420 <pre class="programlisting"><span class="comment">//!Allocates n_elements of elem_bytes bytes.</span>
1421 <span class="comment">//!Throws bad_alloc on failure. chain.size() is not increased on failure.</span>
1422 <span class="keyword">void</span> <span class="identifier">allocate_many</span><span class="special">(</span><span class="identifier">size_type</span> <span class="identifier">elem_bytes</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">n_elements</span><span class="special">,</span> <span class="identifier">multiallocation_chain</span> <span class="special">&amp;</span><span class="identifier">chain</span><span class="special">);</span>
1423
1424 <span class="comment">//!Allocates n_elements, each one of element_lengths[i]*sizeof_element bytes.</span>
1425 <span class="comment">//!Throws bad_alloc on failure. chain.size() is not increased on failure.</span>
1426 <span class="keyword">void</span> <span class="identifier">allocate_many</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">size_type</span> <span class="special">*</span><span class="identifier">element_lengths</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">n_elements</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">sizeof_element</span><span class="special">,</span> <span class="identifier">multiallocation_chain</span> <span class="special">&amp;</span><span class="identifier">chain</span><span class="special">);</span>
1427
1428 <span class="comment">//!Allocates n_elements of elem_bytes bytes.</span>
1429 <span class="comment">//!Non-throwing version. chain.size() is not increased on failure.</span>
1430 <span class="keyword">void</span> <span class="identifier">allocate_many</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow_t</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">elem_bytes</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">n_elements</span><span class="special">,</span> <span class="identifier">multiallocation_chain</span> <span class="special">&amp;</span><span class="identifier">chain</span><span class="special">);</span>
1431
1432 <span class="comment">//!Allocates n_elements, each one of</span>
1433 <span class="comment">//!element_lengths[i]*sizeof_element bytes.</span>
1434 <span class="comment">//!Non-throwing version. chain.size() is not increased on failure.</span>
1435 <span class="keyword">void</span> <span class="identifier">allocate_many</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow_t</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">size_type</span> <span class="special">*</span><span class="identifier">elem_sizes</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">n_elements</span><span class="special">,</span> <span class="identifier">size_type</span> <span class="identifier">sizeof_element</span><span class="special">,</span> <span class="identifier">multiallocation_chain</span> <span class="special">&amp;</span><span class="identifier">chain</span><span class="special">);</span>
1436
1437 <span class="comment">//!Deallocates all elements contained in chain.</span>
1438 <span class="comment">//!Never throws.</span>
1439 <span class="keyword">void</span> <span class="identifier">deallocate_many</span><span class="special">(</span><span class="identifier">multiallocation_chain</span> <span class="special">&amp;</span><span class="identifier">chain</span><span class="special">);</span>
1440 </pre>
1441 <p>
1442           Here is a small example showing all this functionality:
1443         </p>
1444 <p>
1445 </p>
1446 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
1447 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">move</span><span class="special">/</span><span class="identifier">utility_core</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span> <span class="comment">//boost::move</span>
1448 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;//</span><span class="identifier">assert</span>
1449 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstring</span><span class="special">&gt;//</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">memset</span>
1450 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="keyword">new</span><span class="special">&gt;</span>    <span class="comment">//std::nothrow</span>
1451 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span> <span class="comment">//std::vector</span>
1452
1453 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1454 <span class="special">{</span>
1455    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
1456    <span class="keyword">typedef</span> <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">multiallocation_chain</span> <span class="identifier">multiallocation_chain</span><span class="special">;</span>
1457
1458    <span class="comment">//Remove shared memory on construction and destruction</span>
1459    <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
1460    <span class="special">{</span>
1461       <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1462       <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1463    <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
1464
1465    <span class="identifier">managed_shared_memory</span> <span class="identifier">managed_shm</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span><span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="number">65536</span><span class="special">);</span>
1466
1467    <span class="comment">//Allocate 16 elements of 100 bytes in a single call. Non-throwing version.</span>
1468    <span class="identifier">multiallocation_chain</span> <span class="identifier">chain</span><span class="special">;</span>
1469    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocate_many</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">nothrow</span><span class="special">,</span> <span class="number">100</span><span class="special">,</span> <span class="number">16</span><span class="special">,</span> <span class="identifier">chain</span><span class="special">);</span>
1470
1471    <span class="comment">//Check if the memory allocation was successful</span>
1472    <span class="keyword">if</span><span class="special">(</span><span class="identifier">chain</span><span class="special">.</span><span class="identifier">empty</span><span class="special">())</span> <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span>
1473
1474    <span class="comment">//Allocated buffers</span>
1475    <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">*&gt;</span> <span class="identifier">allocated_buffers</span><span class="special">;</span>
1476
1477    <span class="comment">//Initialize our data</span>
1478    <span class="keyword">while</span><span class="special">(!</span><span class="identifier">chain</span><span class="special">.</span><span class="identifier">empty</span><span class="special">()){</span>
1479       <span class="keyword">void</span> <span class="special">*</span><span class="identifier">buf</span> <span class="special">=</span> <span class="identifier">chain</span><span class="special">.</span><span class="identifier">pop_front</span><span class="special">();</span>
1480       <span class="identifier">allocated_buffers</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="identifier">buf</span><span class="special">);</span>
1481       <span class="comment">//The iterator must be incremented before overwriting memory</span>
1482       <span class="comment">//because otherwise, the iterator is invalidated.</span>
1483       <span class="identifier">std</span><span class="special">::</span><span class="identifier">memset</span><span class="special">(</span><span class="identifier">buf</span><span class="special">,</span> <span class="number">0</span><span class="special">,</span> <span class="number">100</span><span class="special">);</span>
1484    <span class="special">}</span>
1485
1486    <span class="comment">//Now deallocate</span>
1487    <span class="keyword">while</span><span class="special">(!</span><span class="identifier">allocated_buffers</span><span class="special">.</span><span class="identifier">empty</span><span class="special">()){</span>
1488       <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span><span class="identifier">allocated_buffers</span><span class="special">.</span><span class="identifier">back</span><span class="special">());</span>
1489       <span class="identifier">allocated_buffers</span><span class="special">.</span><span class="identifier">pop_back</span><span class="special">();</span>
1490    <span class="special">}</span>
1491
1492    <span class="comment">//Allocate 10 buffers of different sizes in a single call. Throwing version</span>
1493    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">sizes</span><span class="special">[</span><span class="number">10</span><span class="special">];</span>
1494    <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="number">10</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>
1495       <span class="identifier">sizes</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">*</span><span class="number">3</span><span class="special">;</span>
1496
1497    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocate_many</span><span class="special">(</span><span class="identifier">sizes</span><span class="special">,</span> <span class="number">10</span><span class="special">,</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">chain</span><span class="special">);</span>
1498    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate_many</span><span class="special">(</span><span class="identifier">chain</span><span class="special">);</span>
1499    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1500 <span class="special">}</span>
1501 </pre>
1502 <p>
1503         </p>
1504 <p>
1505           Allocating N buffers of the same size improves the performance of pools
1506           and node containers (for example STL-like lists): when inserting a range
1507           of forward iterators in a STL-like list, the insertion function can detect
1508           the number of needed elements and allocate in a single call. The nodes
1509           still can be deallocated.
1510         </p>
1511 <p>
1512           Allocating N buffers of different sizes can be used to speed up allocation
1513           in cases where several objects must always be allocated at the same time
1514           but deallocated at different times. For example, a class might perform
1515           several initial allocations (some header data for a network packet, for
1516           example) in its constructor but also allocations of buffers that might
1517           be reallocated in the future (the data to be sent through the network).
1518           Instead of allocating all the data independently, the constructor might
1519           use <code class="computeroutput"><span class="identifier">allocate_many</span><span class="special">()</span></code>
1520           to speed up the initialization, but it still can deallocate and expand
1521           the memory of the variable size element.
1522         </p>
1523 <p>
1524           In general, <code class="computeroutput"><span class="identifier">allocate_many</span></code>
1525           is useful with large values of N. Overuse of <code class="computeroutput"><span class="identifier">allocate_many</span></code>
1526           can increase the effective memory usage, because it can't reuse existing
1527           non-contiguous memory fragments that might be available for some of the
1528           elements.
1529         </p>
1530 </div>
1531 <div class="section">
1532 <div class="titlepage"><div><div><h4 class="title">
1533 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_expand_in_place"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.managed_memory_segment_expand_in_place" title="Expand in place memory allocation">Expand
1534         in place memory allocation</a>
1535 </h4></div></div></div>
1536 <p>
1537           When programming some data structures such as vectors, memory reallocation
1538           becomes an important tool to improve performance. Managed memory segments
1539           offer an advanced reallocation function that offers:
1540         </p>
1541 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1542 <li class="listitem">
1543               Forward expansion: An allocated buffer can be expanded so that the
1544               end of the buffer is moved further. New data can be written between
1545               the old end and the new end.
1546             </li>
1547 <li class="listitem">
1548               Backwards expansion: An allocated buffer can be expanded so that the
1549               beginning of the buffer is moved backwards. New data can be written
1550               between the new beginning and the old beginning.
1551             </li>
1552 <li class="listitem">
1553               Shrinking: An allocated buffer can be shrunk so that the end of the
1554               buffer is moved backwards. The memory between the new end and the old
1555               end can be reused for future allocations.
1556             </li>
1557 </ul></div>
1558 <p>
1559           The expansion can be combined with the allocation of a new buffer if the
1560           expansion fails obtaining a function with "expand, if fails allocate
1561           a new buffer" semantics.
1562         </p>
1563 <p>
1564           Apart from this features, the function always returns the real size of
1565           the allocated buffer, because many times, due to alignment issues the allocated
1566           buffer a bit bigger than the requested size. Thus, the programmer can maximize
1567           the memory use using <code class="computeroutput"><span class="identifier">allocation_command</span></code>.
1568         </p>
1569 <p>
1570           Here is the declaration of the function:
1571         </p>
1572 <pre class="programlisting"><span class="keyword">enum</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocation_type</span>
1573 <span class="special">{</span>
1574    <span class="comment">//Bitwise OR (|) combinable values</span>
1575    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocate_new</span>        <span class="special">=</span> <span class="special">...,</span>
1576    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span>          <span class="special">=</span> <span class="special">...,</span>
1577    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span>          <span class="special">=</span> <span class="special">...,</span>
1578    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">shrink_in_place</span>     <span class="special">=</span> <span class="special">...,</span>
1579    <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span>  <span class="special">=</span> <span class="special">...</span>
1580 <span class="special">};</span>
1581
1582
1583 <span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
1584 <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">T</span> <span class="special">*,</span> <span class="keyword">bool</span><span class="special">&gt;</span>
1585    <span class="identifier">allocation_command</span><span class="special">(</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocation_type</span> <span class="identifier">command</span>
1586                      <span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">limit_size</span>
1587                      <span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">preferred_size</span>
1588                      <span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="special">&amp;</span><span class="identifier">received_size</span>
1589                      <span class="special">,</span> <span class="identifier">T</span> <span class="special">*</span><span class="identifier">reuse_ptr</span> <span class="special">=</span> <span class="number">0</span><span class="special">);</span>
1590 </pre>
1591 <p>
1592           <span class="bold"><strong>Preconditions for the function</strong></span>:
1593         </p>
1594 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1595 <li class="listitem">
1596               If the parameter command contains the value <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">shrink_in_place</span></code>
1597               it can't contain any of these values: <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span></code>,
1598               <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span></code>.
1599             </li>
1600 <li class="listitem">
1601               If the parameter command contains <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span></code>
1602               or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span></code>, the parameter <code class="computeroutput"><span class="identifier">reuse_ptr</span></code> must be non-null and returned
1603               by a previous allocation function.
1604             </li>
1605 <li class="listitem">
1606               If the parameter command contains the value <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">shrink_in_place</span></code>,
1607               the parameter <code class="computeroutput"><span class="identifier">limit_size</span></code>
1608               must be equal or greater than the parameter <code class="computeroutput"><span class="identifier">preferred_size</span></code>.
1609             </li>
1610 <li class="listitem">
1611               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1612               contains any of these values: <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span></code>
1613               or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span></code>, the parameter <code class="computeroutput"><span class="identifier">limit_size</span></code> must be equal or less
1614               than the parameter <code class="computeroutput"><span class="identifier">preferred_size</span></code>.
1615             </li>
1616 </ul></div>
1617 <p>
1618           <span class="bold"><strong>Which are the effects of this function:</strong></span>
1619         </p>
1620 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1621 <li class="listitem">
1622               If the parameter command contains the value <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">shrink_in_place</span></code>,
1623               the function will try to reduce the size of the memory block referenced
1624               by pointer <code class="computeroutput"><span class="identifier">reuse_ptr</span></code>
1625               to the value <code class="computeroutput"><span class="identifier">preferred_size</span></code>
1626               moving only the end of the block. If it's not possible, it will try
1627               to reduce the size of the memory block as much as possible as long
1628               as this results in <code class="computeroutput"><span class="identifier">size</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="identifier">limit_size</span></code>. Success is reported only
1629               if this results in <code class="computeroutput"><span class="identifier">preferred_size</span>
1630               <span class="special">&lt;=</span> <span class="identifier">size</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span></code> and <code class="computeroutput"><span class="identifier">size</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="special">&lt;=</span> <span class="identifier">limit_size</span></code>.
1631             </li>
1632 <li class="listitem">
1633               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1634               only contains the value <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span></code>
1635               (with optional additional <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>),
1636               the allocator will try to increase the size of the memory block referenced
1637               by pointer reuse moving only the end of the block to the value <code class="computeroutput"><span class="identifier">preferred_size</span></code>. If it's not possible,
1638               it will try to increase the size of the memory block as much as possible
1639               as long as this results in <code class="computeroutput"><span class="identifier">size</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="identifier">limit_size</span></code>. Success is reported only
1640               if this results in <code class="computeroutput"><span class="identifier">limit_size</span>
1641               <span class="special">&lt;=</span> <span class="identifier">size</span><span class="special">(</span><span class="identifier">p</span><span class="special">)</span></code>.
1642             </li>
1643 <li class="listitem">
1644               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1645               only contains the value <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span></code>
1646               (with optional additional <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>),
1647               the allocator will try to increase the size of the memory block referenced
1648               by pointer <code class="computeroutput"><span class="identifier">reuse_ptr</span></code>
1649               only moving the start of the block to a returned new position <code class="computeroutput"><span class="identifier">new_ptr</span></code>. If it's not possible, it
1650               will try to move the start of the block as much as possible as long
1651               as this results in <code class="computeroutput"><span class="identifier">size</span><span class="special">(</span><span class="identifier">new_ptr</span><span class="special">)</span> <span class="special">&gt;=</span> <span class="identifier">limit_size</span></code>. Success is reported only
1652               if this results in <code class="computeroutput"><span class="identifier">limit_size</span>
1653               <span class="special">&lt;=</span> <span class="identifier">size</span><span class="special">(</span><span class="identifier">new_ptr</span><span class="special">)</span></code>.
1654             </li>
1655 <li class="listitem">
1656               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1657               only contains the value <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocate_new</span></code>
1658               (with optional additional <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>),
1659               the allocator will try to allocate memory for <code class="computeroutput"><span class="identifier">preferred_size</span></code>
1660               objects. If it's not possible it will try to allocate memory for at
1661               least <code class="computeroutput"><span class="identifier">limit_size</span></code> objects.
1662             </li>
1663 <li class="listitem">
1664               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1665               only contains a combination of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span></code>
1666               and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocate_new</span></code>, (with optional additional
1667               <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>) the allocator
1668               will try first the forward expansion. If this fails, it would try a
1669               new allocation.
1670             </li>
1671 <li class="listitem">
1672               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1673               only contains a combination of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span></code>
1674               and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocate_new</span></code> (with optional additional
1675               <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>), the allocator
1676               will try first to obtain <code class="computeroutput"><span class="identifier">preferred_size</span></code>
1677               objects using both methods if necessary. If this fails, it will try
1678               to obtain <code class="computeroutput"><span class="identifier">limit_size</span></code>
1679               objects using both methods if necessary.
1680             </li>
1681 <li class="listitem">
1682               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1683               only contains a combination of <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span></code>
1684               and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span></code> (with optional additional
1685               <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>), the allocator
1686               will try first forward expansion. If this fails it will try to obtain
1687               preferred_size objects using backwards expansion or a combination of
1688               forward and backwards expansion. If this fails, it will try to obtain
1689               <code class="computeroutput"><span class="identifier">limit_size</span></code> objects
1690               using both methods if necessary.
1691             </li>
1692 <li class="listitem">
1693               If the parameter <code class="computeroutput"><span class="identifier">command</span></code>
1694               only contains a combination of allocation_new, <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span></code>
1695               and <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_bwd</span></code>, (with optional additional
1696               <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>) the allocator
1697               will try first forward expansion. If this fails it will try to obtain
1698               preferred_size objects using new allocation, backwards expansion or
1699               a combination of forward and backwards expansion. If this fails, it
1700               will try to obtain <code class="computeroutput"><span class="identifier">limit_size</span></code>
1701               objects using the same methods.
1702             </li>
1703 <li class="listitem">
1704               The allocator always writes the size or the expanded/allocated/shrunk
1705               memory block in <code class="computeroutput"><span class="identifier">received_size</span></code>.
1706               On failure the allocator writes in <code class="computeroutput"><span class="identifier">received_size</span></code>
1707               a possibly successful <code class="computeroutput"><span class="identifier">limit_size</span></code>
1708               parameter for a new call.
1709             </li>
1710 </ul></div>
1711 <p>
1712           <span class="bold"><strong>Throws an exception if two conditions are met:</strong></span>
1713         </p>
1714 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1715 <li class="listitem">
1716               The allocator is unable to allocate/expand/shrink the memory or there
1717               is an error in preconditions
1718             </li>
1719 <li class="listitem">
1720               The parameter command does not contain <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code>.
1721             </li>
1722 </ul></div>
1723 <p>
1724           <span class="bold"><strong>This function returns:</strong></span>
1725         </p>
1726 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1727 <li class="listitem">
1728               The address of the allocated memory or the new address of the expanded
1729               memory as the first member of the pair. If the parameter command contains
1730               <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">nothrow_allocation</span></code> the first member
1731               will be 0 if the allocation/expansion fails or there is an error in
1732               preconditions.
1733             </li>
1734 <li class="listitem">
1735               The second member of the pair will be false if the memory has been
1736               allocated, true if the memory has been expanded. If the first member
1737               is 0, the second member has an undefined value.
1738             </li>
1739 </ul></div>
1740 <p>
1741           <span class="bold"><strong>Notes:</strong></span>
1742         </p>
1743 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1744 <li class="listitem">
1745               If the user chooses <code class="computeroutput"><span class="keyword">char</span></code>
1746               as template argument the returned buffer will be suitably aligned to
1747               hold any type.
1748             </li>
1749 <li class="listitem">
1750               If the user chooses <code class="computeroutput"><span class="keyword">char</span></code>
1751               as template argument and a backwards expansion is performed, although
1752               properly aligned, the returned buffer might not be suitable because
1753               the distance between the new beginning and the old beginning might
1754               not multiple of the type the user wants to construct, since due to
1755               internal restrictions the expansion can be slightly bigger than the
1756               requested bytes. <span class="bold"><strong>When performing backwards expansion,
1757               if you have already constructed objects in the old buffer, make sure
1758               to specify correctly the type.</strong></span>
1759             </li>
1760 </ul></div>
1761 <p>
1762           Here is a small example that shows the use of <code class="computeroutput"><span class="identifier">allocation_command</span></code>:
1763         </p>
1764 <p>
1765 </p>
1766 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_shared_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
1767 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cassert</span><span class="special">&gt;</span>
1768
1769 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1770 <span class="special">{</span>
1771    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
1772
1773    <span class="comment">//Remove shared memory on construction and destruction</span>
1774    <span class="keyword">struct</span> <span class="identifier">shm_remove</span>
1775    <span class="special">{</span>
1776       <span class="identifier">shm_remove</span><span class="special">()</span> <span class="special">{</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1777       <span class="special">~</span><span class="identifier">shm_remove</span><span class="special">(){</span> <span class="identifier">shared_memory_object</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="string">"MySharedMemory"</span><span class="special">);</span> <span class="special">}</span>
1778    <span class="special">}</span> <span class="identifier">remover</span><span class="special">;</span>
1779
1780    <span class="comment">//Managed memory segment that allocates portions of a shared memory</span>
1781    <span class="comment">//segment with the default management algorithm</span>
1782    <span class="identifier">managed_shared_memory</span> <span class="identifier">managed_shm</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="string">"MySharedMemory"</span><span class="special">,</span> <span class="number">10000</span><span class="special">*</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">));</span>
1783
1784    <span class="comment">//Allocate at least 100 bytes, 1000 bytes if possible</span>
1785    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">min_size</span> <span class="special">=</span> <span class="number">100</span><span class="special">,</span> <span class="identifier">preferred_size</span> <span class="special">=</span> <span class="number">1000</span><span class="special">;</span>
1786    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">received_size</span><span class="special">;</span>
1787    <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="special">*</span><span class="identifier">ptr</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocation_command</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&gt;</span>
1788       <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">allocate_new</span><span class="special">,</span> <span class="identifier">min_size</span><span class="special">,</span> <span class="identifier">preferred_size</span><span class="special">,</span> <span class="identifier">received_size</span><span class="special">).</span><span class="identifier">first</span><span class="special">;</span>
1789
1790    <span class="comment">//Received size must be bigger than min_size</span>
1791    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">received_size</span> <span class="special">&gt;=</span> <span class="identifier">min_size</span><span class="special">);</span>
1792
1793    <span class="comment">//Get free memory</span>
1794    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">free_memory_after_allocation</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_free_memory</span><span class="special">();</span>
1795
1796    <span class="comment">//Now write the data</span>
1797    <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">received_size</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span> <span class="identifier">ptr</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">;</span>
1798
1799    <span class="comment">//Now try to triplicate the buffer. We won't admit an expansion</span>
1800    <span class="comment">//lower to the double of the original buffer.</span>
1801    <span class="comment">//This "should" be successful since no other class is allocating</span>
1802    <span class="comment">//memory from the segment</span>
1803    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">expanded_size</span><span class="special">;</span>
1804    <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="special">*,</span> <span class="keyword">bool</span><span class="special">&gt;</span> <span class="identifier">ret</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocation_command</span>
1805       <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">expand_fwd</span><span class="special">,</span> <span class="identifier">received_size</span><span class="special">*</span><span class="number">2</span><span class="special">,</span> <span class="identifier">received_size</span><span class="special">*</span><span class="number">3</span><span class="special">,</span> <span class="identifier">expanded_size</span><span class="special">,</span> <span class="identifier">ptr</span><span class="special">);</span>
1806
1807    <span class="comment">//Check invariants</span>
1808    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">ret</span><span class="special">.</span><span class="identifier">second</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span>
1809    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">ret</span><span class="special">.</span><span class="identifier">first</span> <span class="special">==</span> <span class="identifier">ptr</span><span class="special">);</span>
1810    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">expanded_size</span> <span class="special">&gt;=</span> <span class="identifier">received_size</span><span class="special">*</span><span class="number">2</span><span class="special">);</span>
1811
1812    <span class="comment">//Get free memory and compare</span>
1813    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">free_memory_after_expansion</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_free_memory</span><span class="special">();</span>
1814    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">free_memory_after_expansion</span> <span class="special">&lt;</span> <span class="identifier">free_memory_after_allocation</span><span class="special">);</span>
1815
1816    <span class="comment">//Write new values</span>
1817    <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">received_size</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">expanded_size</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">)</span>  <span class="identifier">ptr</span><span class="special">[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">;</span>
1818
1819    <span class="comment">//Try to shrink approximately to min_size, but the new size</span>
1820    <span class="comment">//should be smaller than min_size*2.</span>
1821    <span class="comment">//This "should" be successful since no other class is allocating</span>
1822    <span class="comment">//memory from the segment</span>
1823    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">shrunk_size</span><span class="special">;</span>
1824    <span class="identifier">ret</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">allocation_command</span>
1825       <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">shrink_in_place</span><span class="special">,</span> <span class="identifier">min_size</span><span class="special">*</span><span class="number">2</span><span class="special">,</span> <span class="identifier">min_size</span><span class="special">,</span> <span class="identifier">shrunk_size</span><span class="special">,</span> <span class="identifier">ptr</span><span class="special">);</span>
1826
1827    <span class="comment">//Check invariants</span>
1828    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">ret</span><span class="special">.</span><span class="identifier">second</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span>
1829    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">ret</span><span class="special">.</span><span class="identifier">first</span> <span class="special">==</span> <span class="identifier">ptr</span><span class="special">);</span>
1830    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">shrunk_size</span> <span class="special">&lt;=</span> <span class="identifier">min_size</span><span class="special">*</span><span class="number">2</span><span class="special">);</span>
1831    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">shrunk_size</span> <span class="special">&gt;=</span> <span class="identifier">min_size</span><span class="special">);</span>
1832
1833    <span class="comment">//Get free memory and compare</span>
1834    <span class="identifier">managed_shared_memory</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">free_memory_after_shrinking</span> <span class="special">=</span> <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">get_free_memory</span><span class="special">();</span>
1835    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">free_memory_after_shrinking</span> <span class="special">&gt;</span> <span class="identifier">free_memory_after_expansion</span><span class="special">);</span>
1836
1837    <span class="comment">//Deallocate the buffer</span>
1838    <span class="identifier">managed_shm</span><span class="special">.</span><span class="identifier">deallocate</span><span class="special">(</span><span class="identifier">ptr</span><span class="special">);</span>
1839    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1840 <span class="special">}</span>
1841 </pre>
1842 <p>
1843         </p>
1844 <p>
1845           <code class="computeroutput"><span class="identifier">allocation_command</span></code> is a
1846           very powerful function that can lead to important performance gains. It's
1847           specially useful when programming vector-like data structures where the
1848           programmer can minimize both the number of allocation requests and the
1849           memory waste.
1850         </p>
1851 </div>
1852 <div class="section">
1853 <div class="titlepage"><div><div><h4 class="title">
1854 <a name="interprocess.managed_memory_segments.managed_memory_segment_advanced_features.copy_on_write_read_only"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_memory_segment_advanced_features.copy_on_write_read_only" title="Opening managed shared memory and mapped files with Copy On Write or Read Only modes">Opening
1855         managed shared memory and mapped files with Copy On Write or Read Only modes</a>
1856 </h4></div></div></div>
1857 <p>
1858           When mapping a memory segment based on shared memory or files, there is
1859           an option to open them using <span class="bold"><strong>open_copy_on_write</strong></span>
1860           option. This option is similar to <code class="computeroutput"><span class="identifier">open_only</span></code>
1861           but every change the programmer does with this managed segment is kept
1862           private to this process and is not translated to the underlying device
1863           (shared memory or file).
1864         </p>
1865 <p>
1866           The underlying shared memory or file is opened as read-only so several
1867           processes can share an initial managed segment and make private changes
1868           to it. If many processes open a managed segment in copy on write mode and
1869           not modified pages from the managed segment will be shared between all
1870           those processes, with considerable memory savings.
1871         </p>
1872 <p>
1873           Opening managed shared memory and mapped files with <span class="bold"><strong>open_read_only</strong></span>
1874           maps the underlying device in memory with <span class="bold"><strong>read-only</strong></span>
1875           attributes. This means that any attempt to write that memory, either creating
1876           objects or locking any mutex might result in an page-fault error (and thus,
1877           program termination) from the OS. Read-only mode opens the underlying device
1878           (shared memory, file...) in read-only mode and can result in considerable
1879           memory savings if several processes just want to process a managed memory
1880           segment without modifying it. Read-only mode operations are limited:
1881         </p>
1882 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1883 <li class="listitem">
1884               Read-only mode must be used only from managed classes. If the programmer
1885               obtains the segment manager and tries to use it directly it might result
1886               in an access violation. The reason for this is that the segment manager
1887               is placed in the underlying device and does not nothing about the mode
1888               it's been mapped in memory.
1889             </li>
1890 <li class="listitem">
1891               Only const member functions from managed segments should be used.
1892             </li>
1893 <li class="listitem">
1894               Additionally, the <code class="computeroutput"><span class="identifier">find</span><span class="special">&lt;&gt;</span></code> member function avoids using
1895               internal locks and can be used to look for named and unique objects.
1896             </li>
1897 </ul></div>
1898 <p>
1899           Here is an example that shows the use of these two open modes:
1900         </p>
1901 <p>
1902 </p>
1903 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_mapped_file</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
1904 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">fstream</span><span class="special">&gt;</span> <span class="comment">//std::fstream</span>
1905 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iterator</span><span class="special">&gt;//</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">distance</span>
1906
1907
1908 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
1909 <span class="special">{</span>
1910    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
1911
1912    <span class="comment">//Define file names</span>
1913    <span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span><span class="identifier">ManagedFile</span>  <span class="special">=</span> <span class="string">"MyManagedFile"</span><span class="special">;</span>
1914    <span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span><span class="identifier">ManagedFile2</span> <span class="special">=</span> <span class="string">"MyManagedFile2"</span><span class="special">;</span>
1915
1916    <span class="comment">//Try to erase any previous managed segment with the same name</span>
1917    <span class="identifier">file_mapping</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="identifier">ManagedFile</span><span class="special">);</span>
1918    <span class="identifier">file_mapping</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="identifier">ManagedFile2</span><span class="special">);</span>
1919    <span class="identifier">remove_file_on_destroy</span> <span class="identifier">destroyer1</span><span class="special">(</span><span class="identifier">ManagedFile</span><span class="special">);</span>
1920    <span class="identifier">remove_file_on_destroy</span> <span class="identifier">destroyer2</span><span class="special">(</span><span class="identifier">ManagedFile2</span><span class="special">);</span>
1921
1922    <span class="special">{</span>
1923       <span class="comment">//Create an named integer in a managed mapped file</span>
1924       <span class="identifier">managed_mapped_file</span> <span class="identifier">managed_file</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="identifier">ManagedFile</span><span class="special">,</span> <span class="number">65536</span><span class="special">);</span>
1925       <span class="identifier">managed_file</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt"</span><span class="special">)(</span><span class="number">0u</span><span class="special">);</span>
1926
1927       <span class="comment">//Now create a copy on write version</span>
1928       <span class="identifier">managed_mapped_file</span> <span class="identifier">managed_file_cow</span><span class="special">(</span><span class="identifier">open_copy_on_write</span><span class="special">,</span> <span class="identifier">ManagedFile</span><span class="special">);</span>
1929
1930       <span class="comment">//Erase the int and create a new one</span>
1931       <span class="keyword">if</span><span class="special">(!</span><span class="identifier">managed_file_cow</span><span class="special">.</span><span class="identifier">destroy</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt"</span><span class="special">))</span>
1932          <span class="keyword">throw</span> <span class="keyword">int</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
1933       <span class="identifier">managed_file_cow</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt2"</span><span class="special">);</span>
1934
1935       <span class="comment">//Check changes</span>
1936       <span class="keyword">if</span><span class="special">(</span><span class="identifier">managed_file_cow</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt"</span><span class="special">).</span><span class="identifier">first</span> <span class="special">&amp;&amp;</span> <span class="special">!</span><span class="identifier">managed_file_cow</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt2"</span><span class="special">).</span><span class="identifier">first</span><span class="special">)</span>
1937          <span class="keyword">throw</span> <span class="keyword">int</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
1938
1939       <span class="comment">//Check the original is intact</span>
1940       <span class="keyword">if</span><span class="special">(!</span><span class="identifier">managed_file</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt"</span><span class="special">).</span><span class="identifier">first</span> <span class="special">&amp;&amp;</span> <span class="identifier">managed_file</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt2"</span><span class="special">).</span><span class="identifier">first</span><span class="special">)</span>
1941          <span class="keyword">throw</span> <span class="keyword">int</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
1942
1943       <span class="special">{</span>  <span class="comment">//Dump the modified copy on write segment to a file</span>
1944          <span class="identifier">std</span><span class="special">::</span><span class="identifier">fstream</span> <span class="identifier">file</span><span class="special">(</span><span class="identifier">ManagedFile2</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">out</span> <span class="special">|</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ios_base</span><span class="special">::</span><span class="identifier">binary</span><span class="special">);</span>
1945          <span class="keyword">if</span><span class="special">(!</span><span class="identifier">file</span><span class="special">)</span>
1946             <span class="keyword">throw</span> <span class="keyword">int</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
1947        <span class="identifier">file</span><span class="special">.</span><span class="identifier">write</span><span class="special">(</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*&gt;(</span><span class="identifier">managed_file_cow</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">()),</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">streamsize</span><span class="special">)</span><span class="identifier">managed_file_cow</span><span class="special">.</span><span class="identifier">get_size</span><span class="special">());</span>
1948       <span class="special">}</span>
1949
1950       <span class="comment">//Now open the modified file and test changes</span>
1951       <span class="identifier">managed_mapped_file</span> <span class="identifier">managed_file_cow2</span><span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span> <span class="identifier">ManagedFile2</span><span class="special">);</span>
1952       <span class="keyword">if</span><span class="special">(</span><span class="identifier">managed_file_cow2</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt"</span><span class="special">).</span><span class="identifier">first</span> <span class="special">&amp;&amp;</span> <span class="special">!</span><span class="identifier">managed_file_cow2</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt2"</span><span class="special">).</span><span class="identifier">first</span><span class="special">)</span>
1953          <span class="keyword">throw</span> <span class="keyword">int</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
1954    <span class="special">}</span>
1955    <span class="special">{</span>
1956       <span class="comment">//Now create a read-only version</span>
1957       <span class="identifier">managed_mapped_file</span> <span class="identifier">managed_file_ro</span><span class="special">(</span><span class="identifier">open_read_only</span><span class="special">,</span> <span class="identifier">ManagedFile</span><span class="special">);</span>
1958
1959       <span class="comment">//Check the original is intact</span>
1960       <span class="keyword">if</span><span class="special">(!</span><span class="identifier">managed_file_ro</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt"</span><span class="special">).</span><span class="identifier">first</span> <span class="special">&amp;&amp;</span> <span class="identifier">managed_file_ro</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="string">"MyInt2"</span><span class="special">).</span><span class="identifier">first</span><span class="special">)</span>
1961          <span class="keyword">throw</span> <span class="keyword">int</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
1962
1963       <span class="comment">//Check the number of named objects using the iterators</span>
1964       <span class="keyword">if</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">distance</span><span class="special">(</span><span class="identifier">managed_file_ro</span><span class="special">.</span><span class="identifier">named_begin</span><span class="special">(),</span>  <span class="identifier">managed_file_ro</span><span class="special">.</span><span class="identifier">named_end</span><span class="special">())</span>  <span class="special">!=</span> <span class="number">1</span> <span class="special">&amp;&amp;</span>
1965          <span class="identifier">std</span><span class="special">::</span><span class="identifier">distance</span><span class="special">(</span><span class="identifier">managed_file_ro</span><span class="special">.</span><span class="identifier">unique_begin</span><span class="special">(),</span> <span class="identifier">managed_file_ro</span><span class="special">.</span><span class="identifier">unique_end</span><span class="special">())</span> <span class="special">!=</span> <span class="number">0</span> <span class="special">)</span>
1966          <span class="keyword">throw</span> <span class="keyword">int</span><span class="special">(</span><span class="number">0</span><span class="special">);</span>
1967    <span class="special">}</span>
1968    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
1969 <span class="special">}</span>
1970 </pre>
1971 <p>
1972         </p>
1973 </div>
1974 </div>
1975 <div class="section">
1976 <div class="titlepage"><div><div><h3 class="title">
1977 <a name="interprocess.managed_memory_segments.managed_heap_memory_external_buffer"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer" title="Managed Heap Memory And Managed External Buffer">Managed
1978       Heap Memory And Managed External Buffer</a>
1979 </h3></div></div></div>
1980 <div class="toc"><dl class="toc">
1981 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_external_buffer">Managed
1982         External Buffer: Constructing all Boost.Interprocess objects in a user provided
1983         buffer</a></span></dt>
1984 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_heap_memory">Managed
1985         Heap Memory: Boost.Interprocess machinery in heap memory</a></span></dt>
1986 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_heap_memory_external_buffer_diff">Differences
1987         between managed memory segments</a></span></dt>
1988 <dt><span class="section"><a href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.shared_message_queue_ex">Example:
1989         Serializing a database through the message queue</a></span></dt>
1990 </dl></div>
1991 <p>
1992         <span class="bold"><strong>Boost.Interprocess</strong></span> offers managed shared
1993         memory between processes using <code class="computeroutput"><span class="identifier">managed_shared_memory</span></code>
1994         or <code class="computeroutput"><span class="identifier">managed_mapped_file</span></code>. Two
1995         processes just map the same the memory mappable resource and read from and
1996         write to that object.
1997       </p>
1998 <p>
1999         Many times, we don't want to use that shared memory approach and we prefer
2000         to send serialized data through network, local socket or message queues.
2001         Serialization can be done through <span class="bold"><strong>Boost.Serialization</strong></span>
2002         or similar library. However, if two processes share the same ABI (application
2003         binary interface), we could use the same object and container construction
2004         capabilities of <code class="computeroutput"><span class="identifier">managed_shared_memory</span></code>
2005         or <code class="computeroutput"><span class="identifier">managed_heap_memory</span></code> to
2006         build all the information in a single buffer that will be sent, for example,
2007         though message queues. The receiver would just copy the data to a local buffer,
2008         and it could read or modify it directly without deserializing the data .
2009         This approach can be much more efficient that a complex serialization mechanism.
2010       </p>
2011 <p>
2012         Applications for <span class="bold"><strong>Boost.Interprocess</strong></span> services
2013         using non-shared memory buffers:
2014       </p>
2015 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
2016 <li class="listitem">
2017             Create and use STL compatible containers and allocators, in systems where
2018             dynamic memory is not recommendable.
2019           </li>
2020 <li class="listitem">
2021             Build complex, easily serializable databases in a single buffer:
2022             <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
2023 <li class="listitem">
2024                   To share data between threads
2025                 </li>
2026 <li class="listitem">
2027                   To save and load information from/to files.
2028                 </li>
2029 </ul></div>
2030           </li>
2031 <li class="listitem">
2032             Duplicate information (containers, allocators, etc...) just copying the
2033             contents of one buffer to another one.
2034           </li>
2035 <li class="listitem">
2036             Send complex information and objects/databases using serial/inter-process/network
2037             communications.
2038           </li>
2039 </ul></div>
2040 <p>
2041         To help with this management, <span class="bold"><strong>Boost.Interprocess</strong></span>
2042         provides two useful classes, <code class="computeroutput"><span class="identifier">basic_managed_heap_memory</span></code>
2043         and <code class="computeroutput"><span class="identifier">basic_managed_external_buffer</span></code>:
2044       </p>
2045 <div class="section">
2046 <div class="titlepage"><div><div><h4 class="title">
2047 <a name="interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_external_buffer"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_external_buffer" title="Managed External Buffer: Constructing all Boost.Interprocess objects in a user provided buffer">Managed
2048         External Buffer: Constructing all Boost.Interprocess objects in a user provided
2049         buffer</a>
2050 </h4></div></div></div>
2051 <p>
2052           Sometimes, the user wants to create simple objects, STL compatible containers,
2053           STL compatible strings and more, all in a single buffer. This buffer could
2054           be a big static buffer, a memory-mapped auxiliary device or any other user
2055           buffer.
2056         </p>
2057 <p>
2058           This would allow an easy serialization and we-ll just need to copy the
2059           buffer to duplicate all the objects created in the original buffer, including
2060           complex objects like maps, lists.... <span class="bold"><strong>Boost.Interprocess</strong></span>
2061           offers managed memory segment classes to handle user provided buffers that
2062           allow the same functionality as shared memory classes:
2063         </p>
2064 <pre class="programlisting"><span class="comment">//Named object creation managed memory segment</span>
2065 <span class="comment">//All objects are constructed in a user provided buffer</span>
2066 <span class="keyword">template</span> <span class="special">&lt;</span>
2067             <span class="keyword">class</span> <span class="identifier">CharType</span><span class="special">,</span>
2068             <span class="keyword">class</span> <span class="identifier">MemoryAlgorithm</span><span class="special">,</span>
2069             <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>
2070          <span class="special">&gt;</span>
2071 <span class="keyword">class</span> <span class="identifier">basic_managed_external_buffer</span><span class="special">;</span>
2072
2073 <span class="comment">//Named object creation managed memory segment</span>
2074 <span class="comment">//All objects are constructed in a user provided buffer</span>
2075 <span class="comment">//   Names are c-strings,</span>
2076 <span class="comment">//   Default memory management algorithm</span>
2077 <span class="comment">//    (rbtree_best_fit with no mutexes and relative pointers)</span>
2078 <span class="comment">//   Name-object mappings are stored in the default index type (flat_map)</span>
2079 <span class="keyword">typedef</span> <span class="identifier">basic_managed_external_buffer</span> <span class="special">&lt;</span>
2080    <span class="keyword">char</span><span class="special">,</span>
2081    <span class="identifier">rbtree_best_fit</span><span class="special">&lt;</span><span class="identifier">null_mutex_family</span><span class="special">,</span> <span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;,</span>
2082    <span class="identifier">flat_map_index</span>
2083    <span class="special">&gt;</span>  <span class="identifier">managed_external_buffer</span><span class="special">;</span>
2084
2085 <span class="comment">//Named object creation managed memory segment</span>
2086 <span class="comment">//All objects are constructed in a user provided buffer</span>
2087 <span class="comment">//   Names are wide-strings,</span>
2088 <span class="comment">//   Default memory management algorithm</span>
2089 <span class="comment">//    (rbtree_best_fit with no mutexes and relative pointers)</span>
2090 <span class="comment">//   Name-object mappings are stored in the default index type (flat_map)</span>
2091 <span class="keyword">typedef</span> <span class="identifier">basic_managed_external_buffer</span><span class="special">&lt;</span>
2092    <span class="keyword">wchar_t</span><span class="special">,</span>
2093    <span class="identifier">rbtree_best_fit</span><span class="special">&lt;</span><span class="identifier">null_mutex_family</span><span class="special">,</span> <span class="identifier">offset_ptr</span><span class="special">&lt;</span><span class="keyword">void</span><span class="special">&gt;</span> <span class="special">&gt;,</span>
2094    <span class="identifier">flat_map_index</span>
2095    <span class="special">&gt;</span>  <span class="identifier">wmanaged_external_buffer</span><span class="special">;</span>
2096 </pre>
2097 <p>
2098           To use a managed external buffer, you must include the following header:
2099         </p>
2100 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_external_buffer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2101 </pre>
2102 <p>
2103           Let's see an example of the use of managed_external_buffer:
2104         </p>
2105 <p>
2106 </p>
2107 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_external_buffer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2108 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">allocators</span><span class="special">/</span><span class="identifier">allocator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2109 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">containers</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2110 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstring</span><span class="special">&gt;</span>
2111 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">aligned_storage</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2112
2113 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
2114 <span class="special">{</span>
2115    <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
2116
2117    <span class="comment">//Create the static memory who will store all objects</span>
2118    <span class="keyword">const</span> <span class="keyword">int</span> <span class="identifier">memsize</span> <span class="special">=</span> <span class="number">65536</span><span class="special">;</span>
2119
2120    <span class="keyword">static</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">aligned_storage</span><span class="special">&lt;</span><span class="identifier">memsize</span><span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">static_buffer</span><span class="special">;</span>
2121
2122    <span class="comment">//This managed memory will construct objects associated with</span>
2123    <span class="comment">//a wide string in the static buffer</span>
2124    <span class="identifier">wmanaged_external_buffer</span> <span class="identifier">objects_in_static_memory</span>
2125       <span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">static_buffer</span><span class="special">,</span> <span class="identifier">memsize</span><span class="special">);</span>
2126
2127    <span class="comment">//We optimize resources to create 100 named objects in the static buffer</span>
2128    <span class="identifier">objects_in_static_memory</span><span class="special">.</span><span class="identifier">reserve_named_objects</span><span class="special">(</span><span class="number">100</span><span class="special">);</span>
2129
2130    <span class="comment">//Alias an integer node allocator type</span>
2131    <span class="comment">//This allocator will allocate memory inside the static buffer</span>
2132    <span class="keyword">typedef</span> <span class="identifier">allocator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">wmanaged_external_buffer</span><span class="special">::</span><span class="identifier">segment_manager</span><span class="special">&gt;</span>
2133       <span class="identifier">allocator_t</span><span class="special">;</span>
2134
2135    <span class="comment">//Alias a STL compatible list to be constructed in the static buffer</span>
2136    <span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">allocator_t</span><span class="special">&gt;</span>    <span class="identifier">MyBufferList</span><span class="special">;</span>
2137
2138    <span class="comment">//The list must be initialized with the allocator</span>
2139    <span class="comment">//All objects created with objects_in_static_memory will</span>
2140    <span class="comment">//be stored in the static_buffer!</span>
2141    <span class="identifier">MyBufferList</span> <span class="special">*</span><span class="identifier">list</span> <span class="special">=</span> <span class="identifier">objects_in_static_memory</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyBufferList</span><span class="special">&gt;(</span><span class="identifier">L</span><span class="string">"MyList"</span><span class="special">)</span>
2142                            <span class="special">(</span><span class="identifier">objects_in_static_memory</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">());</span>
2143    <span class="comment">//Since the allocation algorithm from wmanaged_external_buffer uses relative</span>
2144    <span class="comment">//pointers and all the pointers constructed int the static memory point</span>
2145    <span class="comment">//to objects in the same segment,  we can create another static buffer</span>
2146    <span class="comment">//from the first one and duplicate all the data.</span>
2147    <span class="keyword">static</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">aligned_storage</span><span class="special">&lt;</span><span class="identifier">memsize</span><span class="special">&gt;::</span><span class="identifier">type</span> <span class="identifier">static_buffer2</span><span class="special">;</span>
2148    <span class="identifier">std</span><span class="special">::</span><span class="identifier">memcpy</span><span class="special">(&amp;</span><span class="identifier">static_buffer2</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">static_buffer</span><span class="special">,</span> <span class="identifier">memsize</span><span class="special">);</span>
2149
2150    <span class="comment">//Now open the duplicated managed memory passing the memory as argument</span>
2151    <span class="identifier">wmanaged_external_buffer</span> <span class="identifier">objects_in_static_memory2</span>
2152       <span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">static_buffer2</span><span class="special">,</span> <span class="identifier">memsize</span><span class="special">);</span>
2153
2154    <span class="comment">//Check that "MyList" has been duplicated in the second buffer</span>
2155    <span class="keyword">if</span><span class="special">(!</span><span class="identifier">objects_in_static_memory2</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="identifier">MyBufferList</span><span class="special">&gt;(</span><span class="identifier">L</span><span class="string">"MyList"</span><span class="special">).</span><span class="identifier">first</span><span class="special">)</span>
2156       <span class="keyword">return</span> <span class="number">1</span><span class="special">;</span>
2157
2158    <span class="comment">//Destroy the lists from the static buffers</span>
2159    <span class="identifier">objects_in_static_memory</span><span class="special">.</span><span class="identifier">destroy</span><span class="special">&lt;</span><span class="identifier">MyBufferList</span><span class="special">&gt;(</span><span class="identifier">L</span><span class="string">"MyList"</span><span class="special">);</span>
2160    <span class="identifier">objects_in_static_memory2</span><span class="special">.</span><span class="identifier">destroy</span><span class="special">&lt;</span><span class="identifier">MyBufferList</span><span class="special">&gt;(</span><span class="identifier">L</span><span class="string">"MyList"</span><span class="special">);</span>
2161    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
2162 <span class="special">}</span>
2163 </pre>
2164 <p>
2165         </p>
2166 <p>
2167           <span class="bold"><strong>Boost.Interprocess</strong></span> STL compatible allocators
2168           can also be used to place STL compatible containers in the user segment.
2169         </p>
2170 <p>
2171           <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed__idp65246848.html" title="Class template basic_managed_external_buffer">basic_managed_external_buffer</a></code>
2172           can be also useful to build small databases for embedded systems limiting
2173           the size of the used memory to a predefined memory chunk, instead of letting
2174           the database fragment the heap memory.
2175         </p>
2176 </div>
2177 <div class="section">
2178 <div class="titlepage"><div><div><h4 class="title">
2179 <a name="interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_heap_memory"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_heap_memory" title="Managed Heap Memory: Boost.Interprocess machinery in heap memory">Managed
2180         Heap Memory: Boost.Interprocess machinery in heap memory</a>
2181 </h4></div></div></div>
2182 <p>
2183           The use of heap memory (new/delete) to obtain a buffer where the user wants
2184           to store all his data is very common, so <span class="bold"><strong>Boost.Interprocess</strong></span>
2185           provides some specialized classes that work exclusively with heap memory.
2186         </p>
2187 <p>
2188           These are the classes:
2189         </p>
2190 <pre class="programlisting"><span class="comment">//Named object creation managed memory segment</span>
2191 <span class="comment">//All objects are constructed in a single buffer allocated via new[]</span>
2192 <span class="keyword">template</span> <span class="special">&lt;</span>
2193             <span class="keyword">class</span> <span class="identifier">CharType</span><span class="special">,</span>
2194             <span class="keyword">class</span> <span class="identifier">MemoryAlgorithm</span><span class="special">,</span>
2195             <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>
2196          <span class="special">&gt;</span>
2197 <span class="keyword">class</span> <span class="identifier">basic_managed_heap_memory</span><span class="special">;</span>
2198
2199 <span class="comment">//Named object creation managed memory segment</span>
2200 <span class="comment">//All objects are constructed in a single buffer allocated via new[]</span>
2201 <span class="comment">//   Names are c-strings,</span>
2202 <span class="comment">//   Default memory management algorithm</span>
2203 <span class="comment">//    (rbtree_best_fit with no mutexes and relative pointers)</span>
2204 <span class="comment">//   Name-object mappings are stored in the default index type (flat_map)</span>
2205 <span class="keyword">typedef</span> <span class="identifier">basic_managed_heap_memory</span> <span class="special">&lt;</span>
2206    <span class="keyword">char</span><span class="special">,</span>
2207    <span class="identifier">rbtree_best_fit</span><span class="special">&lt;</span><span class="identifier">null_mutex_family</span><span class="special">&gt;,</span>
2208    <span class="identifier">flat_map_index</span>
2209    <span class="special">&gt;</span>  <span class="identifier">managed_heap_memory</span><span class="special">;</span>
2210
2211 <span class="comment">//Named object creation managed memory segment</span>
2212 <span class="comment">//All objects are constructed in a single buffer allocated via new[]</span>
2213 <span class="comment">//   Names are wide-strings,</span>
2214 <span class="comment">//   Default memory management algorithm</span>
2215 <span class="comment">//    (rbtree_best_fit with no mutexes and relative pointers)</span>
2216 <span class="comment">//   Name-object mappings are stored in the default index type (flat_map)</span>
2217 <span class="keyword">typedef</span> <span class="identifier">basic_managed_heap_memory</span><span class="special">&lt;</span>
2218    <span class="keyword">wchar_t</span><span class="special">,</span>
2219    <span class="identifier">rbtree_best_fit</span><span class="special">&lt;</span><span class="identifier">null_mutex_family</span><span class="special">&gt;,</span>
2220    <span class="identifier">flat_map_index</span>
2221    <span class="special">&gt;</span>  <span class="identifier">wmanaged_heap_memory</span><span class="special">;</span>
2222 </pre>
2223 <p>
2224           To use a managed heap memory, you must include the following header:
2225         </p>
2226 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_heap_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2227 </pre>
2228 <p>
2229           The use is exactly the same as <code class="computeroutput"><a class="link" href="../boost/interprocess/basic_managed__idp65246848.html" title="Class template basic_managed_external_buffer">basic_managed_external_buffer</a></code>,
2230           except that memory is created by the managed memory segment itself using
2231           dynamic (new/delete) memory.
2232         </p>
2233 <p>
2234           <span class="bold"><strong>basic_managed_heap_memory</strong></span> also offers
2235           a <code class="computeroutput"><span class="identifier">grow</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">extra_bytes</span><span class="special">)</span></code> function that tries to resize internal
2236           heap memory so that we have room for more objects. But <span class="bold"><strong>be
2237           careful</strong></span>, if memory is reallocated, the old buffer will be copied
2238           into the new one so all the objects will be binary-copied to the new buffer.
2239           To be able to use this function, all pointers constructed in the heap buffer
2240           that point to objects in the heap buffer must be relative pointers (for
2241           example <code class="computeroutput"><span class="identifier">offset_ptr</span></code>). Otherwise,
2242           the result is undefined. Here is an example:
2243         </p>
2244 <p>
2245 </p>
2246 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">containers</span><span class="special">/</span><span class="identifier">list</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2247 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">managed_heap_memory</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2248 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">interprocess</span><span class="special">/</span><span class="identifier">allocators</span><span class="special">/</span><span class="identifier">allocator</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
2249 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">cstddef</span><span class="special">&gt;</span>
2250
2251 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">;</span>
2252 <span class="keyword">typedef</span> <span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">allocator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">managed_heap_memory</span><span class="special">::</span><span class="identifier">segment_manager</span><span class="special">&gt;</span> <span class="special">&gt;</span>
2253    <span class="identifier">MyList</span><span class="special">;</span>
2254
2255 <span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span>
2256 <span class="special">{</span>
2257    <span class="comment">//We will create a buffer of 1000 bytes to store a list</span>
2258    <span class="identifier">managed_heap_memory</span> <span class="identifier">heap_memory</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span>
2259
2260    <span class="identifier">MyList</span> <span class="special">*</span> <span class="identifier">mylist</span> <span class="special">=</span> <span class="identifier">heap_memory</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyList</span><span class="special">&gt;(</span><span class="string">"MyList"</span><span class="special">)</span>
2261                         <span class="special">(</span><span class="identifier">heap_memory</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">());</span>
2262
2263    <span class="comment">//Obtain handle, that identifies the list in the buffer</span>
2264    <span class="identifier">managed_heap_memory</span><span class="special">::</span><span class="identifier">handle_t</span> <span class="identifier">list_handle</span> <span class="special">=</span> <span class="identifier">heap_memory</span><span class="special">.</span><span class="identifier">get_handle_from_address</span><span class="special">(</span><span class="identifier">mylist</span><span class="special">);</span>
2265
2266    <span class="comment">//Fill list until there is no more memory in the buffer</span>
2267    <span class="keyword">try</span><span class="special">{</span>
2268       <span class="keyword">while</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">{</span>
2269          <span class="identifier">mylist</span><span class="special">-&gt;</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">mylist</span><span class="special">-&gt;</span><span class="identifier">begin</span><span class="special">(),</span> <span class="number">0</span><span class="special">);</span>
2270       <span class="special">}</span>
2271    <span class="special">}</span>
2272    <span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">bad_alloc</span> <span class="special">&amp;){</span>
2273       <span class="comment">//memory is full</span>
2274    <span class="special">}</span>
2275    <span class="comment">//Let's obtain the size of the list</span>
2276    <span class="identifier">MyList</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">old_size</span> <span class="special">=</span> <span class="identifier">mylist</span><span class="special">-&gt;</span><span class="identifier">size</span><span class="special">();</span>
2277
2278    <span class="comment">//To make the list bigger, let's increase the heap buffer</span>
2279    <span class="comment">//in 1000 bytes more.</span>
2280    <span class="identifier">heap_memory</span><span class="special">.</span><span class="identifier">grow</span><span class="special">(</span><span class="number">1000</span><span class="special">);</span>
2281
2282    <span class="comment">//If memory has been reallocated, the old pointer is invalid, so</span>
2283    <span class="comment">//use previously obtained handle to find the new pointer.</span>
2284    <span class="identifier">mylist</span> <span class="special">=</span> <span class="keyword">static_cast</span><span class="special">&lt;</span><span class="identifier">MyList</span> <span class="special">*&gt;</span>
2285                <span class="special">(</span><span class="identifier">heap_memory</span><span class="special">.</span><span class="identifier">get_address_from_handle</span><span class="special">(</span><span class="identifier">list_handle</span><span class="special">));</span>
2286
2287    <span class="comment">//Fill list until there is no more memory in the buffer</span>
2288    <span class="keyword">try</span><span class="special">{</span>
2289       <span class="keyword">while</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">{</span>
2290          <span class="identifier">mylist</span><span class="special">-&gt;</span><span class="identifier">insert</span><span class="special">(</span><span class="identifier">mylist</span><span class="special">-&gt;</span><span class="identifier">begin</span><span class="special">(),</span> <span class="number">0</span><span class="special">);</span>
2291       <span class="special">}</span>
2292    <span class="special">}</span>
2293    <span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">bad_alloc</span> <span class="special">&amp;){</span>
2294       <span class="comment">//memory is full</span>
2295    <span class="special">}</span>
2296
2297    <span class="comment">//Let's obtain the new size of the list</span>
2298    <span class="identifier">MyList</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">new_size</span> <span class="special">=</span> <span class="identifier">mylist</span><span class="special">-&gt;</span><span class="identifier">size</span><span class="special">();</span>
2299
2300    <span class="identifier">assert</span><span class="special">(</span><span class="identifier">new_size</span> <span class="special">&gt;</span> <span class="identifier">old_size</span><span class="special">);</span>
2301
2302    <span class="comment">//Destroy list</span>
2303    <span class="identifier">heap_memory</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">mylist</span><span class="special">);</span>
2304
2305    <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
2306 <span class="special">}</span>
2307 </pre>
2308 <p>
2309         </p>
2310 </div>
2311 <div class="section">
2312 <div class="titlepage"><div><div><h4 class="title">
2313 <a name="interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_heap_memory_external_buffer_diff"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.managed_heap_memory_external_buffer_diff" title="Differences between managed memory segments">Differences
2314         between managed memory segments</a>
2315 </h4></div></div></div>
2316 <p>
2317           All managed memory segments have similar capabilities (memory allocation
2318           inside the memory segment, named object construction...), but there are
2319           some remarkable differences between <span class="bold"><strong>managed_shared_memory</strong></span>,
2320           <span class="bold"><strong>managed_mapped_file</strong></span> and <span class="bold"><strong>managed_heap_memory</strong></span>,
2321           <span class="bold"><strong>managed_external_file</strong></span>.
2322         </p>
2323 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
2324 <li class="listitem">
2325               Default specializations of managed shared memory and mapped file use
2326               process-shared mutexes. Heap memory and external buffer have no internal
2327               synchronization by default. The cause is that the first two are thought
2328               to be shared between processes (although memory mapped files could
2329               be used just to obtain a persistent object data-base for a process)
2330               whereas the last two are thought to be used inside one process to construct
2331               a serialized named object data-base that can be sent though serial
2332               interprocess communications (like message queues, localhost network...).
2333             </li>
2334 <li class="listitem">
2335               The first two create a system-global object (a shared memory object
2336               or a file) shared by several processes, whereas the last two are objects
2337               that don't create system-wide resources.
2338             </li>
2339 </ul></div>
2340 </div>
2341 <div class="section">
2342 <div class="titlepage"><div><div><h4 class="title">
2343 <a name="interprocess.managed_memory_segments.managed_heap_memory_external_buffer.shared_message_queue_ex"></a><a class="link" href="managed_memory_segments.html#interprocess.managed_memory_segments.managed_heap_memory_external_buffer.shared_message_queue_ex" title="Example: Serializing a database through the message queue">Example:
2344         Serializing a database through the message queue</a>
2345 </h4></div></div></div>
2346 <p>
2347           To see the utility of managed heap memory and managed external buffer classes,
2348           the following example shows how a message queue can be used to serialize
2349           a whole database constructed in a memory buffer using <span class="bold"><strong>Boost.Interprocess</strong></span>,
2350           send the database through a message queue and duplicated in another buffer:
2351         </p>
2352 <p>
2353 </p>
2354 <pre class="programlisting"><span class="comment">//This test creates a in memory data-base using Interprocess machinery and</span>
2355 <span class="comment">//serializes it through a message queue. Then rebuilds the data-base in</span>
2356 <span class="comment">//another buffer and checks it against the original data-base</span>
2357 <span class="keyword">bool</span> <span class="identifier">test_serialize_db</span><span class="special">()</span>
2358 <span class="special">{</span>
2359    <span class="comment">//Typedef data to create a Interprocess map</span>
2360    <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&gt;</span> <span class="identifier">MyPair</span><span class="special">;</span>
2361    <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&gt;</span>   <span class="identifier">MyLess</span><span class="special">;</span>
2362    <span class="keyword">typedef</span> <span class="identifier">node_allocator</span><span class="special">&lt;</span><span class="identifier">MyPair</span><span class="special">,</span> <span class="identifier">managed_external_buffer</span><span class="special">::</span><span class="identifier">segment_manager</span><span class="special">&gt;</span>
2363       <span class="identifier">node_allocator_t</span><span class="special">;</span>
2364    <span class="keyword">typedef</span> <span class="identifier">map</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span>
2365                <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">,</span>
2366                <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special">&lt;</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">&gt;,</span>
2367                <span class="identifier">node_allocator_t</span><span class="special">&gt;</span>
2368                <span class="identifier">MyMap</span><span class="special">;</span>
2369
2370    <span class="comment">//Some constants</span>
2371    <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">BufferSize</span>  <span class="special">=</span> <span class="number">65536</span><span class="special">;</span>
2372    <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">MaxMsgSize</span>  <span class="special">=</span> <span class="number">100</span><span class="special">;</span>
2373
2374    <span class="comment">//Allocate a memory buffer to hold the destiny database using vector&lt;char&gt;</span>
2375    <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">&gt;</span> <span class="identifier">buffer_destiny</span><span class="special">(</span><span class="identifier">BufferSize</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span>
2376
2377    <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="identifier">test</span><span class="special">::</span><span class="identifier">get_process_id_name</span><span class="special">());</span>
2378    <span class="special">{</span>
2379       <span class="comment">//Create the message-queues</span>
2380       <span class="identifier">message_queue</span> <span class="identifier">mq1</span><span class="special">(</span><span class="identifier">create_only</span><span class="special">,</span> <span class="identifier">test</span><span class="special">::</span><span class="identifier">get_process_id_name</span><span class="special">(),</span> <span class="number">1</span><span class="special">,</span> <span class="identifier">MaxMsgSize</span><span class="special">);</span>
2381
2382       <span class="comment">//Open previously created message-queue simulating other process</span>
2383       <span class="identifier">message_queue</span> <span class="identifier">mq2</span><span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span> <span class="identifier">test</span><span class="special">::</span><span class="identifier">get_process_id_name</span><span class="special">());</span>
2384
2385       <span class="comment">//A managed heap memory to create the origin database</span>
2386       <span class="identifier">managed_heap_memory</span> <span class="identifier">db_origin</span><span class="special">(</span><span class="identifier">buffer_destiny</span><span class="special">.</span><span class="identifier">size</span><span class="special">());</span>
2387
2388       <span class="comment">//Construct the map in the first buffer</span>
2389       <span class="identifier">MyMap</span> <span class="special">*</span><span class="identifier">map1</span> <span class="special">=</span> <span class="identifier">db_origin</span><span class="special">.</span><span class="identifier">construct</span><span class="special">&lt;</span><span class="identifier">MyMap</span><span class="special">&gt;(</span><span class="string">"MyMap"</span><span class="special">)</span>
2390                                        <span class="special">(</span><span class="identifier">MyLess</span><span class="special">(),</span>
2391                                        <span class="identifier">db_origin</span><span class="special">.</span><span class="identifier">get_segment_manager</span><span class="special">());</span>
2392       <span class="keyword">if</span><span class="special">(!</span><span class="identifier">map1</span><span class="special">)</span>
2393          <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
2394
2395       <span class="comment">//Fill map1 until is full</span>
2396       <span class="keyword">try</span><span class="special">{</span>
2397          <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
2398          <span class="keyword">while</span><span class="special">(</span><span class="number">1</span><span class="special">){</span>
2399             <span class="special">(*</span><span class="identifier">map1</span><span class="special">)[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">=</span> <span class="identifier">i</span><span class="special">;</span>
2400             <span class="special">++</span><span class="identifier">i</span><span class="special">;</span>
2401          <span class="special">}</span>
2402       <span class="special">}</span>
2403       <span class="keyword">catch</span><span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">interprocess</span><span class="special">::</span><span class="identifier">bad_alloc</span> <span class="special">&amp;){}</span>
2404
2405       <span class="comment">//Data control data sending through the message queue</span>
2406       <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">sent</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
2407       <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">recvd</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
2408       <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">total_recvd</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
2409       <span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">priority</span><span class="special">;</span>
2410
2411       <span class="comment">//Send whole first buffer through the mq1, read it</span>
2412       <span class="comment">//through mq2 to the second buffer</span>
2413       <span class="keyword">while</span><span class="special">(</span><span class="number">1</span><span class="special">){</span>
2414          <span class="comment">//Send a fragment of buffer1 through mq1</span>
2415        <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">bytes_to_send</span> <span class="special">=</span> <span class="identifier">MaxMsgSize</span> <span class="special">&lt;</span> <span class="special">(</span><span class="identifier">db_origin</span><span class="special">.</span><span class="identifier">get_size</span><span class="special">()</span> <span class="special">-</span> <span class="identifier">sent</span><span class="special">)</span> <span class="special">?</span>
2416                                        <span class="identifier">MaxMsgSize</span> <span class="special">:</span> <span class="special">(</span><span class="identifier">db_origin</span><span class="special">.</span><span class="identifier">get_size</span><span class="special">()</span> <span class="special">-</span> <span class="identifier">sent</span><span class="special">);</span>
2417          <span class="identifier">mq1</span><span class="special">.</span><span class="identifier">send</span><span class="special">(</span> <span class="special">&amp;</span><span class="keyword">static_cast</span><span class="special">&lt;</span><span class="keyword">char</span><span class="special">*&gt;(</span><span class="identifier">db_origin</span><span class="special">.</span><span class="identifier">get_address</span><span class="special">())[</span><span class="identifier">sent</span><span class="special">]</span>
2418                <span class="special">,</span> <span class="identifier">bytes_to_send</span>
2419                <span class="special">,</span> <span class="number">0</span><span class="special">);</span>
2420          <span class="identifier">sent</span> <span class="special">+=</span> <span class="identifier">bytes_to_send</span><span class="special">;</span>
2421          <span class="comment">//Receive the fragment through mq2 to buffer_destiny</span>
2422        <span class="identifier">mq2</span><span class="special">.</span><span class="identifier">receive</span><span class="special">(</span> <span class="special">&amp;</span><span class="identifier">buffer_destiny</span><span class="special">[</span><span class="identifier">total_recvd</span><span class="special">]</span>
2423                 <span class="special">,</span> <span class="identifier">BufferSize</span> <span class="special">-</span> <span class="identifier">recvd</span>
2424                   <span class="special">,</span> <span class="identifier">recvd</span>
2425                   <span class="special">,</span> <span class="identifier">priority</span><span class="special">);</span>
2426          <span class="identifier">total_recvd</span> <span class="special">+=</span> <span class="identifier">recvd</span><span class="special">;</span>
2427
2428          <span class="comment">//Check if we have received all the buffer</span>
2429          <span class="keyword">if</span><span class="special">(</span><span class="identifier">total_recvd</span> <span class="special">==</span> <span class="identifier">BufferSize</span><span class="special">){</span>
2430             <span class="keyword">break</span><span class="special">;</span>
2431          <span class="special">}</span>
2432       <span class="special">}</span>
2433
2434       <span class="comment">//The buffer will contain a copy of the original database</span>
2435       <span class="comment">//so let's interpret the buffer with managed_external_buffer</span>
2436       <span class="identifier">managed_external_buffer</span> <span class="identifier">db_destiny</span><span class="special">(</span><span class="identifier">open_only</span><span class="special">,</span> <span class="special">&amp;</span><span class="identifier">buffer_destiny</span><span class="special">[</span><span class="number">0</span><span class="special">],</span> <span class="identifier">BufferSize</span><span class="special">);</span>
2437
2438       <span class="comment">//Let's find the map</span>
2439       <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span><span class="special">&lt;</span><span class="identifier">MyMap</span> <span class="special">*,</span> <span class="identifier">managed_external_buffer</span><span class="special">::</span><span class="identifier">size_type</span><span class="special">&gt;</span> <span class="identifier">ret</span> <span class="special">=</span> <span class="identifier">db_destiny</span><span class="special">.</span><span class="identifier">find</span><span class="special">&lt;</span><span class="identifier">MyMap</span><span class="special">&gt;(</span><span class="string">"MyMap"</span><span class="special">);</span>
2440       <span class="identifier">MyMap</span> <span class="special">*</span><span class="identifier">map2</span> <span class="special">=</span> <span class="identifier">ret</span><span class="special">.</span><span class="identifier">first</span><span class="special">;</span>
2441
2442       <span class="comment">//Check if we have found it</span>
2443       <span class="keyword">if</span><span class="special">(!</span><span class="identifier">map2</span><span class="special">){</span>
2444          <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
2445       <span class="special">}</span>
2446
2447       <span class="comment">//Check if it is a single variable (not an array)</span>
2448       <span class="keyword">if</span><span class="special">(</span><span class="identifier">ret</span><span class="special">.</span><span class="identifier">second</span> <span class="special">!=</span> <span class="number">1</span><span class="special">){</span>
2449          <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
2450       <span class="special">}</span>
2451
2452       <span class="comment">//Now let's compare size</span>
2453       <span class="keyword">if</span><span class="special">(</span><span class="identifier">map1</span><span class="special">-&gt;</span><span class="identifier">size</span><span class="special">()</span> <span class="special">!=</span> <span class="identifier">map2</span><span class="special">-&gt;</span><span class="identifier">size</span><span class="special">()){</span>
2454          <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
2455       <span class="special">}</span>
2456
2457       <span class="comment">//Now let's compare all db values</span>
2458      <span class="identifier">MyMap</span><span class="special">::</span><span class="identifier">size_type</span> <span class="identifier">num_elements</span> <span class="special">=</span> <span class="identifier">map1</span><span class="special">-&gt;</span><span class="identifier">size</span><span class="special">();</span>
2459      <span class="keyword">for</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">i</span> <span class="special">&lt;</span> <span class="identifier">num_elements</span><span class="special">;</span> <span class="special">++</span><span class="identifier">i</span><span class="special">){</span>
2460          <span class="keyword">if</span><span class="special">((*</span><span class="identifier">map1</span><span class="special">)[</span><span class="identifier">i</span><span class="special">]</span> <span class="special">!=</span> <span class="special">(*</span><span class="identifier">map2</span><span class="special">)[</span><span class="identifier">i</span><span class="special">]){</span>
2461             <span class="keyword">return</span> <span class="keyword">false</span><span class="special">;</span>
2462          <span class="special">}</span>
2463       <span class="special">}</span>
2464
2465       <span class="comment">//Destroy maps from db-s</span>
2466       <span class="identifier">db_origin</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">map1</span><span class="special">);</span>
2467       <span class="identifier">db_destiny</span><span class="special">.</span><span class="identifier">destroy_ptr</span><span class="special">(</span><span class="identifier">map2</span><span class="special">);</span>
2468    <span class="special">}</span>
2469    <span class="identifier">message_queue</span><span class="special">::</span><span class="identifier">remove</span><span class="special">(</span><span class="identifier">test</span><span class="special">::</span><span class="identifier">get_process_id_name</span><span class="special">());</span>
2470    <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span>
2471 <span class="special">}</span>
2472 </pre>
2473 <p>
2474         </p>
2475 </div>
2476 </div>
2477 </div>
2478 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
2479 <td align="left"></td>
2480 <td align="right"><div class="copyright-footer">Copyright &#169; 2005-2012 Ion Gaztanaga<p>
2481         Distributed under the Boost Software License, Version 1.0. (See accompanying
2482         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>)
2483       </p>
2484 </div></td>
2485 </tr></table>
2486 <hr>
2487 <div class="spirit-nav">
2488 <a accesskey="p" href="synchronization_mechanisms.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="allocators_containers.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
2489 </div>
2490 </body>
2491 </html>