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