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
 143    <para>
 144      The only allocator interface that
 145      is supported is the standard C++ interface. As such, all STL
 146      containers have been adjusted, and all external allocators have
 147      been modified to support this change.
 148    </para>
 149
 150    <para>
 151      The class <classname>allocator</classname> just has typedef,
 152    constructor, and rebind members. It inherits from one of the
 153    high-speed extension allocators, covered below. Thus, all
 154    allocation and deallocation depends on the base class.
 155    </para>
 156
 157    <para>
 158      The base class that <classname>allocator</classname> is derived from
 159      may not be user-configurable.
 160 </para>
 161
 162   </section>
 163
 164   <section xml:id="allocator.default"><info><title>Selecting Default Allocation Policy</title></info>
 165
 166
 167    <para>
 168      It's difficult to pick an allocation strategy that will provide
 169    maximum utility, without excessively penalizing some behavior. In
 170    fact, it's difficult just deciding which typical actions to measure
 171    for speed.
 172    </para>
 173
 174    <para>
 175      Three synthetic benchmarks have been created that provide data
 176      that is used to compare different C++ allocators. These tests are:
 177    </para>
 178
 179    <orderedlist>
 180      <listitem>
 181        <para>
 182        Insertion.
 183        </para>
 184        <para>
 185        Over multiple iterations, various STL container
 186      objects have elements inserted to some maximum amount. A variety
 187      of allocators are tested.
 188      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>
 189      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>
 190      containers.
 191        </para>
 192
 193      </listitem>
 194
 195      <listitem>
 196        <para>
 197        Insertion and erasure in a multi-threaded environment.
 198        </para>
 199        <para>
 200        This test shows the ability of the allocator to reclaim memory
 201      on a per-thread basis, as well as measuring thread contention
 202      for memory resources.
 203      Test source
 204     <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>.
 205        </para>
 206      </listitem>
 207
 208      <listitem>
 209        <para>
 210          A threaded producer/consumer model.
 211        </para>
 212        <para>
 213        Test source for
 214      <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>
 215      and
 216      <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>
 217      containers.
 218      </para>
 219      </listitem>
 220    </orderedlist>
 221
 222    <para>
 223      The current default choice for
 224      <classname>allocator</classname> is
 225      <classname>__gnu_cxx::new_allocator</classname>.
 226    </para>
 227
 228   </section>
 229
 230   <section xml:id="allocator.caching"><info><title>Disabling Memory Caching</title></info>
 231
 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 </section>
 321
 322 <section xml:id="allocator.ext"><info><title>Extension Allocators</title></info>
 323
 324
 325   <para>
 326     Several other allocators are provided as part of this
 327     implementation.  The location of the extension allocators and their
 328     names have changed, but in all cases, functionality is
 329     equivalent. Starting with gcc-3.4, all extension allocators are
 330     standard style. Before this point, SGI style was the norm. Because of
 331     this, the number of template arguments also changed. Here's a simple
 332     chart to track the changes.
 333   </para>
 334
 335   <para>
 336     More details on each of these extension allocators follows.
 337   </para>
 338    <orderedlist>
 339      <listitem>
 340        <para>
 341        <classname>new_allocator</classname>
 342        </para>
 343        <para>
 344          Simply wraps <function>::operator new</function>
 345          and <function>::operator delete</function>.
 346        </para>
 347      </listitem>
 348      <listitem>
 349        <para>
 350        <classname>malloc_allocator</classname>
 351        </para>
 352        <para>
 353          Simply wraps <function>malloc</function> and
 354          <function>free</function>. There is also a hook for an
 355          out-of-memory handler (for
 356          <function>new</function>/<function>delete</function> this is
 357          taken care of elsewhere).
 358        </para>
 359      </listitem>
 360      <listitem>
 361        <para>
 362        <classname>array_allocator</classname>
 363        </para>
 364        <para>
 365          Allows allocations of known and fixed sizes using existing
 366          global or external storage allocated via construction of
 367          <classname>std::tr1::array</classname> objects. By using this
 368          allocator, fixed size containers (including
 369          <classname>std::string</classname>) can be used without
 370          instances calling <function>::operator new</function> and
 371          <function>::operator delete</function>. This capability
 372          allows the use of STL abstractions without runtime
 373          complications or overhead, even in situations such as program
 374          startup. For usage examples, please consult the testsuite.
 375        </para>
 376      </listitem>
 377      <listitem>
 378        <para>
 379        <classname>debug_allocator</classname>
 380        </para>
 381        <para>
 382          A wrapper around an arbitrary allocator A.  It passes on
 383          slightly increased size requests to A, and uses the extra
 384          memory to store size information.  When a pointer is passed
 385          to <function>deallocate()</function>, the stored size is
 386          checked, and <function>assert()</function> is used to
 387          guarantee they match.
 388        </para>
 389      </listitem>
 390       <listitem>
 391         <para>
 392         <classname>throw_allocator</classname>
 393         </para>
 394         <para>
 395           Includes memory tracking and marking abilities as well as hooks for
 396           throwing exceptions at configurable intervals (including random,
 397           all, none).
 398         </para>
 399       </listitem>
 400      <listitem>
 401        <para>
 402        <classname>__pool_alloc</classname>
 403        </para>
 404        <para>
 405          A high-performance, single pool allocator.  The reusable
 406          memory is shared among identical instantiations of this type.
 407          It calls through <function>::operator new</function> to
 408          obtain new memory when its lists run out.  If a client
 409          container requests a block larger than a certain threshold
 410          size, then the pool is bypassed, and the allocate/deallocate
 411          request is passed to <function>::operator new</function>
 412          directly.
 413        </para>
 414
 415        <para>
 416          Older versions of this class take a boolean template
 417          parameter, called <varname>thr</varname>, and an integer template
 418          parameter, called <varname>inst</varname>.
 419        </para>
 420
 421        <para>
 422          The <varname>inst</varname> number is used to track additional memory
 423       pools.  The point of the number is to allow multiple
 424       instantiations of the classes without changing the semantics at
 425       all.  All three of
 426        </para>
 427
 428    <programlisting>
 429     typedef  __pool_alloc&lt;true,0&gt;    normal;
 430     typedef  __pool_alloc&lt;true,1&gt;    private;
 431     typedef  __pool_alloc&lt;true,42&gt;   also_private;
 432    </programlisting>
 433    <para>
 434      behave exactly the same way.  However, the memory pool for each type
 435       (and remember that different instantiations result in different types)
 436       remains separate.
 437    </para>
 438    <para>
 439      The library uses <emphasis>0</emphasis> in all its instantiations.  If you
 440       wish to keep separate free lists for a particular purpose, use a
 441       different number.
 442    </para>
 443    <para>The <varname>thr</varname> boolean determines whether the
 444    pool should be manipulated atomically or not.  When
 445    <varname>thr</varname> = <constant>true</constant>, the allocator
 446    is thread-safe, while <varname>thr</varname> =
 447    <constant>false</constant>, is slightly faster but unsafe for
 448    multiple threads.
 449    </para>
 450
 451    <para>
 452      For thread-enabled configurations, the pool is locked with a
 453      single big lock. In some situations, this implementation detail
 454      may result in severe performance degradation.
 455    </para>
 456
 457    <para>
 458      (Note that the GCC thread abstraction layer allows us to provide
 459      safe zero-overhead stubs for the threading routines, if threads
 460      were disabled at configuration time.)
 461    </para>
 462      </listitem>
 463
 464      <listitem>
 465        <para>
 466        <classname>__mt_alloc</classname>
 467        </para>
 468        <para>
 469          A high-performance fixed-size allocator with
 470          exponentially-increasing allocations. It has its own
 471          <link linkend="manual.ext.allocator.mt">chapter</link>
 472          in the documentation.
 473        </para>
 474      </listitem>
 475
 476      <listitem>
 477        <para>
 478        <classname>bitmap_allocator</classname>
 479        </para>
 480        <para>
 481          A high-performance allocator that uses a bit-map to keep track
 482          of the used and unused memory locations. It has its own
 483          <link linkend="manual.ext.allocator.bitmap">chapter</link>
 484          in the documentation.
 485        </para>
 486      </listitem>
 487    </orderedlist>
 488 </section>
 489
 490
 491 <bibliography xml:id="allocator.biblio"><info><title>Bibliography</title></info>
 492
 493
 494   <biblioentry>
 495     <citetitle>
 496     ISO/IEC 14882:1998 Programming languages - C++
 497     </citetitle>
 498     <abbrev>
 499       isoc++_1998
 500     </abbrev>
 501     <pagenums>20.4 Memory</pagenums>
 502   </biblioentry>
 503
 504   <biblioentry>
 505       <title>
 506         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 507               xlink:href="http://www.drdobbs.com/the-standard-librarian-what-are-allocato/184403759">
 508       The Standard Librarian: What Are Allocators Good For?
 509         </link>
 510       </title>
 511
 512     <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author>
 513     <publisher>
 514       <publishername>
 515         C/C++ Users Journal
 516       </publishername>
 517     </publisher>
 518   </biblioentry>
 519
 520   <biblioentry>
 521       <title>
 522         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 523               xlink:href="http://www.hoard.org/">
 524       The Hoard Memory Allocator
 525         </link>
 526       </title>
 527
 528     <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author>
 529   </biblioentry>
 530
 531   <biblioentry>
 532       <title>
 533         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 534               xlink:href="http://people.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf">
 535       Reconsidering Custom Memory Allocation
 536         </link>
 537       </title>
 538
 539     <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author>
 540     <author><personname><firstname>Ben</firstname><surname>Zorn</surname></personname></author>
 541     <author><personname><firstname>Kathryn</firstname><surname>McKinley</surname></personname></author>
 542     <copyright>
 543       <year>2002</year>
 544       <holder>OOPSLA</holder>
 545     </copyright>
 546   </biblioentry>
 547
 548
 549   <biblioentry>
 550       <title>
 551         <link xmlns:xlink="http://www.w3.org/1999/xlink"
 552               xlink:href="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html">
 553       Allocator Types
 554         </link>
 555       </title>
 556
 557
 558     <author><personname><firstname>Klaus</firstname><surname>Kreft</surname></personname></author>
 559     <author><personname><firstname>Angelika</firstname><surname>Langer</surname></personname></author>
 560     <publisher>
 561       <publishername>
 562         C/C++ Users Journal
 563       </publishername>
 564     </publisher>
 565   </biblioentry>
 566
 567   <biblioentry>
 568     <citetitle>The C++ Programming Language</citetitle>
 569     <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author>
 570     <copyright>
 571       <year>2000</year>
 572       <holder/>
 573     </copyright>
 574     <pagenums>19.4 Allocators</pagenums>
 575     <publisher>
 576       <publishername>
 577         Addison Wesley
 578       </publishername>
 579     </publisher>
 580   </biblioentry>
 581
 582   <biblioentry>
 583     <citetitle>Yalloc: A Recycling C++ Allocator</citetitle>
 584     <author><personname><firstname>Felix</firstname><surname>Yen</surname></personname></author>
 585   </biblioentry>
 586 </bibliography>
 587
 588 </section>