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<T></classname>. 46 </para> 47 </listitem> 48 <listitem> 49 <para> 50 The interface of the <classname>allocator<T></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<int></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<WonkyWidget></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><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><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><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 <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</programlisting> 296 <para> 297 Likewise, a debugging form of whichever allocator is currently in use: 298 </para> 299 <programlisting> 300 std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > 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<true,0> normal; 430 typedef __pool_alloc<true,1> private; 431 typedef __pool_alloc<true,42> 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> 589