1<section id="std.util.memory.allocator" xreflabel="Allocator"> 2<?dbhtml filename="allocator.html"?> 3 4<sectioninfo> 5 <keywordset> 6 <keyword> 7 ISO C++ 8 </keyword> 9 <keyword> 10 allocator 11 </keyword> 12 </keywordset> 13</sectioninfo> 14 15<title>Allocators</title> 16 17<para> 18 Memory management for Standard Library entities is encapsulated in a 19 class template called <classname>allocator</classname>. The 20 <classname>allocator</classname> abstraction is used throughout the 21 library in <classname>string</classname>, container classes, 22 algorithms, and parts of iostreams. This class, and base classes of 23 it, are the superset of available free store (<quote>heap</quote>) 24 management classes. 25</para> 26 27<section id="allocator.req"> 28<title>Requirements</title> 29 30 <para> 31 The C++ standard only gives a few directives in this area: 32 </para> 33 <itemizedlist> 34 <listitem> 35 <para> 36 When you add elements to a container, and the container must 37 allocate more memory to hold them, the container makes the 38 request via its <type>Allocator</type> template 39 parameter, which is usually aliased to 40 <type>allocator_type</type>. This includes adding chars 41 to the string class, which acts as a regular STL container in 42 this respect. 43 </para> 44 </listitem> 45 <listitem> 46 <para> 47 The default <type>Allocator</type> argument of every 48 container-of-T is <classname>allocator<T></classname>. 49 </para> 50 </listitem> 51 <listitem> 52 <para> 53 The interface of the <classname>allocator<T></classname> class is 54 extremely simple. It has about 20 public declarations (nested 55 typedefs, member functions, etc), but the two which concern us most 56 are: 57 </para> 58 <programlisting> 59 T* allocate (size_type n, const void* hint = 0); 60 void deallocate (T* p, size_type n); 61 </programlisting> 62 63 <para> 64 The <varname>n</varname> arguments in both those 65 functions is a <emphasis>count</emphasis> of the number of 66 <type>T</type>'s to allocate space for, <emphasis>not their 67 total size</emphasis>. 68 (This is a simplification; the real signatures use nested typedefs.) 69 </para> 70 </listitem> 71 <listitem> 72 <para> 73 The storage is obtained by calling <function>::operator 74 new</function>, but it is unspecified when or how 75 often this function is called. The use of the 76 <varname>hint</varname> is unspecified, but intended as an 77 aid to locality if an implementation so 78 desires. <constant>[20.4.1.1]/6</constant> 79 </para> 80 </listitem> 81 </itemizedlist> 82 83 <para> 84 Complete details can be found in the C++ standard, look in 85 <constant>[20.4 Memory]</constant>. 86 </para> 87 88</section> 89 90<section id="allocator.design_issues"> 91<title>Design Issues</title> 92 93 <para> 94 The easiest way of fulfilling the requirements is to call 95 <function>operator new</function> each time a container needs 96 memory, and to call <function>operator delete</function> each time 97 the container releases memory. This method may be <ulink 98 url="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</ulink> 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<int></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<WonkyWidget></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 id="allocator.impl"> 142<title>Implementation</title> 143 144 <section> 145 <title>Interface Design</title> 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> 169 <title>Selecting Default Allocation Policy</title> 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 <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup">sequence</ulink> 193 and <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup">associative</ulink> 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 <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup">here</ulink>. 209 </para> 210 </listitem> 211 212 <listitem> 213 <para> 214 A threaded producer/consumer model. 215 </para> 216 <para> 217 Test source for 218 <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup">sequence</ulink> 219 and 220 <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup">associative</ulink> 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> 235 <title>Disabling Memory Caching</title> 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 id="allocator.using"> 289<title>Using a Specific Allocator</title> 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 <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</programlisting> 300 <para> 301 Likewise, a debugging form of whichever allocator is currently in use: 302 </para> 303 <programlisting> 304 std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > debug_deque; 305 </programlisting> 306</section> 307 308<section id="allocator.custom"> 309<title>Custom Allocators</title> 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 id="allocator.ext"> 327<title>Extension Allocators</title> 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<true,0> normal; 434 typedef __pool_alloc<true,1> private; 435 typedef __pool_alloc<true,42> 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 476 linkend="manual.ext.allocator.mt">here</link>. 477 </para> 478 </listitem> 479 480 <listitem> 481 <para> 482 <classname>bitmap_allocator</classname> 483 </para> 484 <para> 485 A high-performance allocator that uses a bit-map to keep track 486 of the used and unused memory locations. It has its own 487 documentation, found <link 488 linkend="manual.ext.allocator.bitmap">here</link>. 489 </para> 490 </listitem> 491 </orderedlist> 492</section> 493 494 495<bibliography id="allocator.biblio"> 496<title>Bibliography</title> 497 498 <biblioentry> 499 <title> 500 ISO/IEC 14882:1998 Programming languages - C++ 501 </title> 502 <abbrev> 503 isoc++_1998 504 </abbrev> 505 <pagenums>20.4 Memory</pagenums> 506 </biblioentry> 507 508 <biblioentry> 509 <biblioid class="uri"> 510 <ulink url="http://www.drdobbs.com/cpp/184403759"> 511 <citetitle> 512 The Standard Librarian: What Are Allocators Good For? 513 </citetitle> 514 </ulink> 515 </biblioid> 516 <author> 517 <firstname>Matt</firstname> 518 <surname>Austern</surname> 519 </author> 520 <publisher> 521 <publishername> 522 C/C++ Users Journal 523 </publishername> 524 </publisher> 525 </biblioentry> 526 527 <biblioentry> 528 <biblioid class="uri"> 529 <ulink url="http://www.cs.umass.edu/~emery/hoard/"> 530 <citetitle> 531 The Hoard Memory Allocator 532 </citetitle> 533 </ulink> 534 </biblioid> 535 <author> 536 <firstname>Emery</firstname> 537 <surname>Berger</surname> 538 </author> 539 </biblioentry> 540 541 <biblioentry> 542 <biblioid class="uri"> 543 <ulink url="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf"> 544 <citetitle> 545 Reconsidering Custom Memory Allocation 546 </citetitle> 547 </ulink> 548 </biblioid> 549 <author> 550 <firstname>Emery</firstname> 551 <surname>Berger</surname> 552 </author> 553 <author> 554 <firstname>Ben</firstname> 555 <surname>Zorn</surname> 556 </author> 557 <author> 558 <firstname>Kathryn</firstname> 559 <surname>McKinley</surname> 560 </author> 561 <copyright> 562 <year>2002</year> 563 <holder>OOPSLA</holder> 564 </copyright> 565 </biblioentry> 566 567 568 <biblioentry> 569 <biblioid class="uri"> 570 <ulink url="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html"> 571 <citetitle> 572 Allocator Types 573 </citetitle> 574 </ulink> 575 </biblioid> 576 <author> 577 <firstname>Klaus</firstname> 578 <surname>Kreft</surname> 579 </author> 580 <author> 581 <firstname>Angelika</firstname> 582 <surname>Langer</surname> 583 </author> 584 <publisher> 585 <publishername> 586 C/C++ Users Journal 587 </publishername> 588 </publisher> 589 </biblioentry> 590 591 <biblioentry> 592 <title>The C++ Programming Language</title> 593 <author> 594 <firstname>Bjarne</firstname> 595 <surname>Stroustrup</surname> 596 </author> 597 <copyright> 598 <year>2000</year> 599 <holder></holder> 600 </copyright> 601 <pagenums>19.4 Allocators</pagenums> 602 <publisher> 603 <publishername> 604 Addison Wesley 605 </publishername> 606 </publisher> 607 </biblioentry> 608 609 <biblioentry> 610 <title>Yalloc: A Recycling C++ Allocator</title> 611 <author> 612 <firstname>Felix</firstname> 613 <surname>Yen</surname> 614 </author> 615 </biblioentry> 616</bibliography> 617 618</section> 619