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 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 base class that <classname>allocator</classname> is derived from 158 may not be user-configurable. 159</para> 160 161 </section> 162 163 <section xml:id="allocator.default"><info><title>Selecting Default Allocation Policy</title></info> 164 165 <para> 166 It's difficult to pick an allocation strategy that will provide 167 maximum utility, without excessively penalizing some behavior. In 168 fact, it's difficult just deciding which typical actions to measure 169 for speed. 170 </para> 171 172 <para> 173 Three synthetic benchmarks have been created that provide data 174 that is used to compare different C++ allocators. These tests are: 175 </para> 176 177 <orderedlist> 178 <listitem> 179 <para> 180 Insertion. 181 </para> 182 <para> 183 Over multiple iterations, various STL container 184 objects have elements inserted to some maximum amount. A variety 185 of allocators are tested. 186 Test source for <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/gcc/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/sequence.cc?view=markup">sequence</link> 187 and <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/gcc/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert/associative.cc?view=markup">associative</link> 188 containers. 189 </para> 190 191 </listitem> 192 193 <listitem> 194 <para> 195 Insertion and erasure in a multi-threaded environment. 196 </para> 197 <para> 198 This test shows the ability of the allocator to reclaim memory 199 on a per-thread basis, as well as measuring thread contention 200 for memory resources. 201 Test source 202 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/gcc/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/insert_erase/associative.cc?view=markup">here</link>. 203 </para> 204 </listitem> 205 206 <listitem> 207 <para> 208 A threaded producer/consumer model. 209 </para> 210 <para> 211 Test source for 212 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/gcc/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup">sequence</link> 213 and 214 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/viewcvs/gcc/trunk/libstdc++-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup">associative</link> 215 containers. 216 </para> 217 </listitem> 218 </orderedlist> 219 220 <para> 221 The current default choice for 222 <classname>allocator</classname> is 223 <classname>__gnu_cxx::new_allocator</classname>. 224 </para> 225 226 </section> 227 228 <section xml:id="allocator.caching"><info><title>Disabling Memory Caching</title></info> 229 230 <para> 231 In use, <classname>allocator</classname> may allocate and 232 deallocate using implementation-specific strategies and 233 heuristics. Because of this, a given call to an allocator object's 234 <function>allocate</function> member function may not actually 235 call the global <code>operator new</code> and a given call to 236 to the <function>deallocate</function> member function may not 237 call <code>operator delete</code>. 238 </para> 239 240 <para> 241 This can be confusing. 242 </para> 243 244 <para> 245 In particular, this can make debugging memory errors more 246 difficult, especially when using third-party tools like valgrind or 247 debug versions of <function>new</function>. 248 </para> 249 250 <para> 251 There are various ways to solve this problem. One would be to use 252 a custom allocator that just called operators 253 <function>new</function> and <function>delete</function> 254 directly, for every allocation. (See the default allocator, 255 <filename>include/ext/new_allocator.h</filename>, for instance.) 256 However, that option may involve changing source code to use 257 a non-default allocator. Another option is to force the 258 default allocator to remove caching and pools, and to directly 259 allocate with every call of <function>allocate</function> and 260 directly deallocate with every call of 261 <function>deallocate</function>, regardless of efficiency. As it 262 turns out, this last option is also available. 263 </para> 264 265 266 <para> 267 To globally disable memory caching within the library for some of 268 the optional non-default allocators, merely set 269 <constant>GLIBCXX_FORCE_NEW</constant> (with any value) in the 270 system's environment before running the program. If your program 271 crashes with <constant>GLIBCXX_FORCE_NEW</constant> in the 272 environment, it likely means that you linked against objects 273 built against the older library (objects which might still using the 274 cached allocations...). 275 </para> 276 277 </section> 278 279</section> 280 281<section xml:id="allocator.using"><info><title>Using a Specific Allocator</title></info> 282 283 284 <para> 285 You can specify different memory management schemes on a 286 per-container basis, by overriding the default 287 <type>Allocator</type> template parameter. For example, an easy 288 (but non-portable) method of specifying that only <function>malloc</function> or <function>free</function> 289 should be used instead of the default node allocator is: 290 </para> 291 <programlisting> 292 std::list <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</programlisting> 293 <para> 294 Likewise, a debugging form of whichever allocator is currently in use: 295 </para> 296 <programlisting> 297 std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > debug_deque; 298 </programlisting> 299</section> 300 301<section xml:id="allocator.custom"><info><title>Custom Allocators</title></info> 302 303 304 <para> 305 Writing a portable C++ allocator would dictate that the interface 306 would look much like the one specified for 307 <classname>allocator</classname>. Additional member functions, but 308 not subtractions, would be permissible. 309 </para> 310 311 <para> 312 Probably the best place to start would be to copy one of the 313 extension allocators: say a simple one like 314 <classname>new_allocator</classname>. 315 </para> 316 317</section> 318 319<section xml:id="allocator.ext"><info><title>Extension Allocators</title></info> 320 321 322 <para> 323 Several other allocators are provided as part of this 324 implementation. The location of the extension allocators and their 325 names have changed, but in all cases, functionality is 326 equivalent. Starting with gcc-3.4, all extension allocators are 327 standard style. Before this point, SGI style was the norm. Because of 328 this, the number of template arguments also changed. 329 <xref linkend="table.extension_allocators"/> tracks the changes. 330 </para> 331 332 <para> 333 More details on each of these extension allocators follows. 334 </para> 335 <orderedlist> 336 <listitem> 337 <para> 338 <classname>new_allocator</classname> 339 </para> 340 <para> 341 Simply wraps <function>::operator new</function> 342 and <function>::operator delete</function>. 343 </para> 344 </listitem> 345 <listitem> 346 <para> 347 <classname>malloc_allocator</classname> 348 </para> 349 <para> 350 Simply wraps <function>malloc</function> and 351 <function>free</function>. There is also a hook for an 352 out-of-memory handler (for 353 <function>new</function>/<function>delete</function> this is 354 taken care of elsewhere). 355 </para> 356 </listitem> 357 <listitem> 358 <para> 359 <classname>array_allocator</classname> 360 </para> 361 <para> 362 Allows allocations of known and fixed sizes using existing 363 global or external storage allocated via construction of 364 <classname>std::tr1::array</classname> objects. By using this 365 allocator, fixed size containers (including 366 <classname>std::string</classname>) can be used without 367 instances calling <function>::operator new</function> and 368 <function>::operator delete</function>. This capability 369 allows the use of STL abstractions without runtime 370 complications or overhead, even in situations such as program 371 startup. For usage examples, please consult the testsuite. 372 </para> 373 </listitem> 374 <listitem> 375 <para> 376 <classname>debug_allocator</classname> 377 </para> 378 <para> 379 A wrapper around an arbitrary allocator A. It passes on 380 slightly increased size requests to A, and uses the extra 381 memory to store size information. When a pointer is passed 382 to <function>deallocate()</function>, the stored size is 383 checked, and <function>assert()</function> is used to 384 guarantee they match. 385 </para> 386 </listitem> 387 <listitem> 388 <para> 389 <classname>throw_allocator</classname> 390 </para> 391 <para> 392 Includes memory tracking and marking abilities as well as hooks for 393 throwing exceptions at configurable intervals (including random, 394 all, none). 395 </para> 396 </listitem> 397 <listitem> 398 <para> 399 <classname>__pool_alloc</classname> 400 </para> 401 <para> 402 A high-performance, single pool allocator. The reusable 403 memory is shared among identical instantiations of this type. 404 It calls through <function>::operator new</function> to 405 obtain new memory when its lists run out. If a client 406 container requests a block larger than a certain threshold 407 size, then the pool is bypassed, and the allocate/deallocate 408 request is passed to <function>::operator new</function> 409 directly. 410 </para> 411 412 <para> 413 Older versions of this class take a boolean template 414 parameter, called <varname>thr</varname>, and an integer template 415 parameter, called <varname>inst</varname>. 416 </para> 417 418 <para> 419 The <varname>inst</varname> number is used to track additional memory 420 pools. The point of the number is to allow multiple 421 instantiations of the classes without changing the semantics at 422 all. All three of 423 </para> 424 425 <programlisting> 426 typedef __pool_alloc<true,0> normal; 427 typedef __pool_alloc<true,1> private; 428 typedef __pool_alloc<true,42> also_private; 429 </programlisting> 430 <para> 431 behave exactly the same way. However, the memory pool for each type 432 (and remember that different instantiations result in different types) 433 remains separate. 434 </para> 435 <para> 436 The library uses <emphasis>0</emphasis> in all its instantiations. If you 437 wish to keep separate free lists for a particular purpose, use a 438 different number. 439 </para> 440 <para>The <varname>thr</varname> boolean determines whether the 441 pool should be manipulated atomically or not. When 442 <varname>thr</varname> = <constant>true</constant>, the allocator 443 is thread-safe, while <varname>thr</varname> = 444 <constant>false</constant>, is slightly faster but unsafe for 445 multiple threads. 446 </para> 447 448 <para> 449 For thread-enabled configurations, the pool is locked with a 450 single big lock. In some situations, this implementation detail 451 may result in severe performance degradation. 452 </para> 453 454 <para> 455 (Note that the GCC thread abstraction layer allows us to provide 456 safe zero-overhead stubs for the threading routines, if threads 457 were disabled at configuration time.) 458 </para> 459 </listitem> 460 461 <listitem> 462 <para> 463 <classname>__mt_alloc</classname> 464 </para> 465 <para> 466 A high-performance fixed-size allocator with 467 exponentially-increasing allocations. It has its own 468 <link linkend="manual.ext.allocator.mt">chapter</link> 469 in the documentation. 470 </para> 471 </listitem> 472 473 <listitem> 474 <para> 475 <classname>bitmap_allocator</classname> 476 </para> 477 <para> 478 A high-performance allocator that uses a bit-map to keep track 479 of the used and unused memory locations. It has its own 480 <link linkend="manual.ext.allocator.bitmap">chapter</link> 481 in the documentation. 482 </para> 483 </listitem> 484 </orderedlist> 485</section> 486 487 488<bibliography xml:id="allocator.biblio"><info><title>Bibliography</title></info> 489 490 491 <biblioentry> 492 <citetitle> 493 ISO/IEC 14882:1998 Programming languages - C++ 494 </citetitle> 495 <abbrev> 496 isoc++_1998 497 </abbrev> 498 <pagenums>20.4 Memory</pagenums> 499 </biblioentry> 500 501 <biblioentry> 502 <title> 503 <link xmlns:xlink="http://www.w3.org/1999/xlink" 504 xlink:href="https://web.archive.org/web/20190622154249/http://www.drdobbs.com/the-standard-librarian-what-are-allocato/184403759"> 505 The Standard Librarian: What Are Allocators Good For? 506 </link> 507 </title> 508 509 <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author> 510 <publisher> 511 <publishername> 512 C/C++ Users Journal 513 </publishername> 514 </publisher> 515 <pubdate>2000-12</pubdate> 516 </biblioentry> 517 518 <biblioentry> 519 <title> 520 <link xmlns:xlink="http://www.w3.org/1999/xlink" 521 xlink:href="http://hoard.org"> 522 The Hoard Memory Allocator 523 </link> 524 </title> 525 526 <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author> 527 </biblioentry> 528 529 <biblioentry> 530 <title> 531 <link xmlns:xlink="http://www.w3.org/1999/xlink" 532 xlink:href="https://people.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf"> 533 Reconsidering Custom Memory Allocation 534 </link> 535 </title> 536 537 <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author> 538 <author><personname><firstname>Ben</firstname><surname>Zorn</surname></personname></author> 539 <author><personname><firstname>Kathryn</firstname><surname>McKinley</surname></personname></author> 540 <copyright> 541 <year>2002</year> 542 <holder>OOPSLA</holder> 543 </copyright> 544 </biblioentry> 545 546 547 <biblioentry> 548 <title> 549 <link xmlns:xlink="http://www.w3.org/1999/xlink" 550 xlink:href="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html"> 551 Allocator Types 552 </link> 553 </title> 554 555 556 <author><personname><firstname>Klaus</firstname><surname>Kreft</surname></personname></author> 557 <author><personname><firstname>Angelika</firstname><surname>Langer</surname></personname></author> 558 <publisher> 559 <publishername> 560 C/C++ Users Journal 561 </publishername> 562 </publisher> 563 </biblioentry> 564 565 <biblioentry> 566 <citetitle>The C++ Programming Language</citetitle> 567 <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author> 568 <copyright> 569 <year>2000</year> 570 <holder/> 571 </copyright> 572 <pagenums>19.4 Allocators</pagenums> 573 <publisher> 574 <publishername> 575 Addison Wesley 576 </publishername> 577 </publisher> 578 </biblioentry> 579 580 <biblioentry> 581 <citetitle>Yalloc: A Recycling C++ Allocator</citetitle> 582 <author><personname><firstname>Felix</firstname><surname>Yen</surname></personname></author> 583 </biblioentry> 584</bibliography> 585 586</section> 587