libstdc++-v3/doc/xml/manual/allocator.xml

   1 <section xmlns="http://docbook.org/ns/docbook" version="5.0"
   2          xml:id="std.util.memory.allocator" xreflabel="Allocator">
   3 <?dbhtml filename="allocator.html"?>
   4
   5 <info><title>Allocators</title>
   6   <keywordset>
   7     <keyword>ISO C++</keyword>
   8     <keyword>allocator</keyword>
   9   </keywordset>
  10 </info>
  11
  12
  13
  14 <para>
  15  Memory management for Standard Library entities is encapsulated in a
  16  class template called <classname>allocator</classname>. The
  17  <classname>allocator</classname> abstraction is used throughout the
  18  library in <classname>string</classname>, container classes,
  19  algorithms, and parts of iostreams. This class, and base classes of
  20  it, are the superset of available free store (<quote>heap</quote>)
  21  management classes.
  22 </para>
  23
  24 <section xml:id="allocator.req"><info><title>Requirements</title></info>
  25
  26
  27   <para>
  28     The C++ standard only gives a few directives in this area:
  29   </para>
  30    <itemizedlist>
  31      <listitem>
  32       <para>
  33        When you add elements to a container, and the container must
  34        allocate more memory to hold them, the container makes the
  35        request via its <type>Allocator</type> template
  36        parameter, which is usually aliased to
  37        <type>allocator_type</type>.  This includes adding chars
  38        to the string class, which acts as a regular STL container in
  39        this respect.
  40       </para>
  41      </listitem>
  42      <listitem>
  43        <para>
  44        The default <type>Allocator</type> argument of every
  45        container-of-T is <classname>allocator&lt;T&gt;</classname>.
  46        </para>
  47      </listitem>
  48      <listitem>
  49        <para>
  50        The interface of the <classname>allocator&lt;T&gt;</classname> class is
  51          extremely simple.  It has about 20 public declarations (nested
  52          typedefs, member functions, etc), but the two which concern us most
  53          are:
  54        </para>
  55        <programlisting>
  56          T*    allocate   (size_type n, const void* hint = 0);
  57          void  deallocate (T* p, size_type n);
  58        </programlisting>
  59
  60        <para>
  61          The <varname>n</varname> arguments in both those
  62          functions is a <emphasis>count</emphasis> of the number of
  63          <type>T</type>'s to allocate space for, <emphasis>not their
  64          total size</emphasis>.
  65          (This is a simplification; the real signatures use nested typedefs.)
  66        </para>
  67      </listitem>
  68      <listitem>
  69        <para>
  70          The storage is obtained by calling <function>::operator
  71          new</function>, but it is unspecified when or how
  72          often this function is called.  The use of the
  73          <varname>hint</varname> is unspecified, but intended as an
  74          aid to locality if an implementation so
  75          desires. <constant>[20.4.1.1]/6</constant>
  76        </para>
  77       </listitem>
  78    </itemizedlist>
  79
  80    <para>
  81      Complete details can be found in the C++ standard, look in
  82      <constant>[20.4 Memory]</constant>.
  83    </para>
  84
  85 </section>
  86
  87 <section xml:id="allocator.design_issues"><info><title>Design Issues</title></info>
  88
  89
  90   <para>
  91     The easiest way of fulfilling the requirements is to call
  92     <function>operator new</function> each time a container needs
  93     memory, and to call <function>operator delete</function> each time
  94     the container releases memory. This method may be <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</link>
  95     than caching the allocations and re-using previously-allocated
  96     memory, but has the advantage of working correctly across a wide
  97     variety of hardware and operating systems, including large
  98     clusters. The <classname>__gnu_cxx::new_allocator</classname>
  99     implements the simple operator new and operator delete semantics,
 100     while <classname>__gnu_cxx::malloc_allocator</classname>
 101     implements much the same thing, only with the C language functions
 102     <function>std::malloc</function> and <function>std::free</function>.
 103   </para>
 104
 105   <para>
 106     Another approach is to use intelligence within the allocator
 107     class to cache allocations. This extra machinery can take a variety
 108     of forms: a bitmap index, an index into an exponentially increasing
 109     power-of-two-sized buckets, or simpler fixed-size pooling cache.
 110     The cache is shared among all the containers in the program: when
 111     your program's <classname>std::vector&lt;int&gt;</classname> gets
 112   cut in half and frees a bunch of its storage, that memory can be
 113   reused by the private
 114   <classname>std::list&lt;WonkyWidget&gt;</classname> brought in from
 115   a KDE library that you linked against.  And operators
 116   <function>new</function> and <function>delete</function> are not
 117   always called to pass the memory on, either, which is a speed
 118   bonus. Examples of allocators that use these techniques are
 119   <classname>__gnu_cxx::bitmap_allocator</classname>,
 120   <classname>__gnu_cxx::pool_allocator</classname>, and
 121   <classname>__gnu_cxx::__mt_alloc</classname>.
 122   </para>
 123
 124   <para>
 125     Depending on the implementation techniques used, the underlying
 126     operating system, and compilation environment, scaling caching
 127     allocators can be tricky. In particular, order-of-destruction and
 128     order-of-creation for memory pools may be difficult to pin down
 129     with certainty, which may create problems when used with plugins
 130     or loading and unloading shared objects in memory. As such, using
 131     caching allocators on systems that do not support
 132     <function>abi::__cxa_atexit</function> is not recommended.
 133   </para>
 134
 135 </section>
 136
 137 <section xml:id="allocator.impl"><info><title>Implementation</title></info>
 138
 139
 140   <section xml:id="allocator.interface"><info><title>Interface Design</title></info>
 141
 142    <para>
 143      The only allocator interface that
 144      is supported is the standard C++ interface. As such, all STL
 145      containers have been adjusted, and all external allocators have
 146      been modified to support this change.
 147    </para>
 148
 149    <para>
 150      The class <classname>allocator</classname> just has typedef,
 151    constructor, and rebind members. It inherits from one of the
 152    high-speed extension allocators, covered below. Thus, all
 153    allocation and deallocation depends on the base class.
 154    </para>
 155
 156    <para>
 157      The choice of base class that <classname>allocator</classname>
 158      is derived from is fixed at the time when GCC is built,
 159      and the different choices are not ABI compatible.
 160 </para>
 161
 162   </section>
 163
 164   <section xml:id="allocator.default"><info><title>Selecting Default Allocation Policy</title></info>
 165
 166    <para>
 167      It's difficult to pick an allocation strategy that will provide
 168    maximum utility, without excessively penalizing some behavior. In
 169    fact, it's difficult just deciding which typical actions to measure
 170    for speed.
 171    </para>
 172
 173    <para>
 174      Three synthetic benchmarks have been created that provide data
 175      that is used to compare different C++ allocators. These tests are:
 176    </para>
 177
 178    <orderedlist>
 179      <listitem>
 180        <para>
 181        Insertion.
 182        </para>
 183        <para>
 184        Over multiple iterations, various STL container
 185      objects have elements inserted to some maximum amount. A variety
 186      of allocators are tested.
 187      Test source for <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/insert/sequence.cc">sequence</link>
 188      and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/insert/associative.cc">associative</link>
 189      containers.
 190        </para>
 191
 192      </listitem>
 193
 194      <listitem>
 195        <para>
 196        Insertion and erasure in a multi-threaded environment.
 197        </para>
 198        <para>
 199        This test shows the ability of the allocator to reclaim memory
 200      on a per-thread basis, as well as measuring thread contention
 201      for memory resources.
 202      Test source
 203     <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/insert_erase/associative.cc">here</link>.
 204        </para>
 205      </listitem>
 206
 207      <listitem>
 208        <para>
 209          A threaded producer/consumer model.
 210        </para>
 211        <para>
 212        Test source for
 213      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc">sequence</link>
 214      and
 215      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/cgit/gcc/tree/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/associative.cc">associative</link>
 216      containers.
 217      </para>
 218      </listitem>
 219    </orderedlist>
 220
 221    <para>
 222      Since GCC 12 the default choice for
 223      <classname>allocator</classname> is
 224      <classname>std::__new_allocator</classname>.
 225      Before GCC 12 it was the <classname>__gnu_cxx::new_allocator</classname>
 226      extension (which has identical behaviour).
 227    </para>
 228
 229   </section>
 230
 231   <section xml:id="allocator.caching"><info><title>Disabling Memory Caching</title></info>
 232
 233     <para>
 234       In use, <classname>allocator</classname> may allocate and
 235       deallocate using implementation-specific strategies and
 236       heuristics. Because of this, a given call to an allocator object's
 237       <function>allocate</function> member function may not actually
 238       call the global <code>operator new</code> and a given call to
 239       to the <function>deallocate</function> member function may not
 240       call <code>operator delete</code>.
 241     </para>
 242
 243    <para>
 244      This can be confusing.
 245    </para>
 246
 247    <para>
 248      In particular, this can make debugging memory errors more
 249      difficult, especially when using third-party tools like valgrind or
 250      debug versions of <function>new</function>.
 251    </para>
 252
 253    <para>
 254      There are various ways to solve this problem. One would be to use
 255      a custom allocator that just called operators
 256      <function>new</function> and <function>delete</function>
 257      directly, for every allocation. (See the default allocator,
 258      <filename>include/ext/new_allocator.h</filename>, for instance.)
 259      However, that option may involve changing source code to use
 260      a non-default allocator. Another option is to force the
 261      default allocator to remove caching and pools, and to directly
 262      allocate with every call of <function>allocate</function> and
 263      directly deallocate with every call of
 264      <function>deallocate</function>, regardless of efficiency. As it
 265      turns out, this last option is also available.
 266    </para>
 267
 268
 269    <para>
 270      To globally disable memory caching within the library for some of
 271      the optional non-default allocators, merely set
 272      <constant>GLIBCXX_FORCE_NEW</constant> (with any value) in the
 273      system's environment before running the program. If your program
 274      crashes with <constant>GLIBCXX_FORCE_NEW</constant> in the
 275      environment, it likely means that you linked against objects
 276      built against the older library (objects which might still using the
 277      cached allocations...).
 278   </para>
 279
 280   </section>
 281
 282 </section>
 283
 284 <section xml:id="allocator.using"><info><title>Using a Specific Allocator</title></info>
 285
 286
 287    <para>
 288      You can specify different memory management schemes on a
 289      per-container basis, by overriding the default
 290      <type>Allocator</type> template parameter.  For example, an easy
 291       (but non-portable) method of specifying that only <function>malloc</function> or <function>free</function>
 292       should be used instead of the default node allocator is:
 293    </para>
 294    <programlisting>
 295     std::list &lt;int, __gnu_cxx::malloc_allocator&lt;int&gt; &gt;  malloc_list;</programlisting>
 296     <para>
 297       Likewise, a debugging form of whichever allocator is currently in use:
 298     </para>
 299       <programlisting>
 300     std::deque &lt;int, __gnu_cxx::debug_allocator&lt;std::allocator&lt;int&gt; &gt; &gt;  debug_deque;
 301       </programlisting>
 302 </section>
 303
 304 <section xml:id="allocator.custom"><info><title>Custom Allocators</title></info>
 305
 306
 307   <para>
 308     Writing a portable C++ allocator would dictate that the interface
 309     would look much like the one specified for
 310     <classname>allocator</classname>. Additional member functions, but
 311     not subtractions, would be permissible.
 312   </para>
 313
 314    <para>
 315      Probably the best place to start would be to copy one of the
 316    extension allocators: say a simple one like
 317    <classname>new_allocator</classname>.
 318    </para>
 319
 320    <para>
 321      Since C++11 the minimal interface require for an allocator is
 322      much smaller, as <classname>std::allocator_traits</classname>
 323      can provide default for much of the interface.
 324    </para>
 325
 326
 327 </section>
 328
 329 <section xml:id="allocator.ext"><info><title>Extension Allocators</title></info>
 330
 331
 332   <para>
 333     Several other allocators are provided as part of this
 334     implementation.  The location of the extension allocators and their
 335     names have changed, but in all cases, functionality is
 336     equivalent. Starting with gcc-3.4, all extension allocators are
 337     standard style. Before this point, SGI style was the norm. Because of
 338     this, the number of template arguments also changed.
 339     <xref linkend="table.extension_allocators"/> tracks the changes.
 340   </para>
 341
 342   <para>
 343     More details on each of these extension allocators follows.
 344   </para>
 345    <orderedlist>
 346      <listitem>
 347        <para>
 348        <classname>new_allocator</classname>
 349        </para>
 350        <para>
 351          Simply wraps <function>::operator new</function>
 352          and <function>::operator delete</function>.
 353        </para>
 354      </listitem>
 355      <listitem>
 356        <para>
 357        <classname>malloc_allocator</classname>
 358        </para>
 359        <para>
 360          Simply wraps <function>malloc</function> and
 361          <function>free</function>. There is also a hook for an
 362          out-of-memory handler (for
 363          <function>new</function>/<function>delete</function> this is
 364          taken care of elsewhere).
 365        </para>
 366      </listitem>
 367      <listitem>
 368        <para>
 369        <classname>debug_allocator</classname>
 370        </para>
 371        <para>
 372          A wrapper around an arbitrary allocator <classname>A</classname>.
 373          It passes on slightly increased size requests to <classname>A</classname>,
 374          and uses the extra memory to store size information.
 375          When a pointer is passed
 376          to <function>deallocate()</function>, the stored size is
 377          checked, and <function>assert()</function> is used to
 378          guarantee they match.
 379        </para>
 380      </listitem>
 381       <listitem>
 382         <para>
 383         <classname>throw_allocator</classname>
 384         </para>
 385         <para>
 386           Includes memory tracking and marking abilities as well as hooks for
 387           throwing exceptions at configurable intervals (including random,
 388           all, none).
 389         </para>
 390       </listitem>
 391      <listitem>
 392        <para>
 393        <classname>__pool_alloc</classname>
 394        </para>
 395        <para>
 396          A high-performance, single pool allocator.  The reusable
 397          memory is shared among identical instantiations of this type.
 398          It calls through <function>::operator new</function> to
 399          obtain new memory when its lists run out.  If a client
 400          container requests a block larger than a certain threshold
 401          size, then the pool is bypassed, and the allocate/deallocate
 402          request is passed to <function>::operator new</function>
 403          directly.
 404        </para>
 405
 406        <para>
 407          For thread-enabled configurations, the pool is locked with a
 408          single big lock. In some situations, this implementation detail
 409          may result in severe performance degradation.
 410        </para>
 411
 412        <para>
 413          (Note that the GCC thread abstraction layer allows us to provide
 414          safe zero-overhead stubs for the threading routines, if threads
 415          were disabled at configuration time.)
 416        </para>
 417      </listitem>
 418
 419      <listitem>
 420        <para>
 421        <classname>__mt_alloc</classname>
 422        </para>
 423        <para>
 424          A high-performance fixed-size allocator with
 425          exponentially-increasing allocations. It has its own
 426          <link linkend="manual.ext.allocator.mt">chapter</link>
 427          in the documentation.
 428        </para>
 429      </listitem>
 430
 431      <listitem>
 432        <para>
 433        <classname>bitmap_allocator</classname>
 434        </para>
 435        <para>
 436          A high-performance allocator that uses a bit-map to keep track
 437          of the used and unused memory locations. It has its own
 438          <link linkend="manual.ext.allocator.bitmap">chapter</link>
 439          in the documentation.
 440        </para>
 441      </listitem>
 442    </orderedlist>
 443 </section>
 444
 445
 446 <bibliography xml:id="allocator.biblio"><info><title>Bibliography</title></info>
 447
 448
 449   <biblioentry>
 450     <citetitle>
 451     ISO/IEC 14882:1998 Programming languages - C++
 452     </citetitle>
 453     <abbrev>
 454       isoc++_1998
 455     </abbrev>
 456     <pagenums>20.4 Memory</pagenums>
 457   </biblioentry>
 458
 459   <biblioentry>
 460     <title>
 461       <link xmlns:xlink="http://www.w3.org/1999/xlink"
 462             xlink:href="https://web.archive.org/web/20190622154249/http://www.drdobbs.com/the-standard-librarian-what-are-allocato/184403759">
 463       The Standard Librarian: What Are Allocators Good For?
 464       </link>
 465     </title>
 466
 467     <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author>
 468     <publisher>
 469       <publishername>
 470         C/C++ Users Journal
 471       </publishername>
 472     </publisher>
 473     <pubdate>2000-12</pubdate>
 474   </biblioentry>
 475
 476   <biblioentry>
 477       <title>
 478         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 479               xlink:href="http://hoard.org">
 480       The Hoard Memory Allocator
 481         </link>
 482       </title>
 483
 484     <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author>
 485   </biblioentry>
 486
 487   <biblioentry>
 488       <title>
 489         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 490               xlink:href="https://people.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf">
 491       Reconsidering Custom Memory Allocation
 492         </link>
 493       </title>
 494
 495     <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author>
 496     <author><personname><firstname>Ben</firstname><surname>Zorn</surname></personname></author>
 497     <author><personname><firstname>Kathryn</firstname><surname>McKinley</surname></personname></author>
 498     <copyright>
 499       <year>2002</year>
 500       <holder>OOPSLA</holder>
 501     </copyright>
 502   </biblioentry>
 503
 504
 505   <biblioentry>
 506       <title>
 507         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 508               xlink:href="https://angelikalanger.com/Articles/C++Report/Allocators/Allocators.html">
 509       Allocator Types
 510         </link>
 511       </title>
 512
 513
 514     <author><personname><firstname>Klaus</firstname><surname>Kreft</surname></personname></author>
 515     <author><personname><firstname>Angelika</firstname><surname>Langer</surname></personname></author>
 516     <publisher>
 517       <publishername>
 518         C/C++ Users Journal
 519       </publishername>
 520     </publisher>
 521   </biblioentry>
 522
 523   <biblioentry>
 524     <citetitle>The C++ Programming Language</citetitle>
 525     <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author>
 526     <copyright>
 527       <year>2000</year>
 528       <holder/>
 529     </copyright>
 530     <pagenums>19.4 Allocators</pagenums>
 531     <publisher>
 532       <publishername>
 533         Addison Wesley
 534       </publishername>
 535     </publisher>
 536   </biblioentry>
 537
 538   <biblioentry>
 539     <citetitle>Yalloc: A Recycling C++ Allocator</citetitle>
 540     <author><personname><firstname>Felix</firstname><surname>Yen</surname></personname></author>
 541   </biblioentry>
 542 </bibliography>
 543
 544 </section>