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>debug_allocator</classname> 360 </para> 361 <para> 362 A wrapper around an arbitrary allocator A. It passes on 363 slightly increased size requests to A, and uses the extra 364 memory to store size information. When a pointer is passed 365 to <function>deallocate()</function>, the stored size is 366 checked, and <function>assert()</function> is used to 367 guarantee they match. 368 </para> 369 </listitem> 370 <listitem> 371 <para> 372 <classname>throw_allocator</classname> 373 </para> 374 <para> 375 Includes memory tracking and marking abilities as well as hooks for 376 throwing exceptions at configurable intervals (including random, 377 all, none). 378 </para> 379 </listitem> 380 <listitem> 381 <para> 382 <classname>__pool_alloc</classname> 383 </para> 384 <para> 385 A high-performance, single pool allocator. The reusable 386 memory is shared among identical instantiations of this type. 387 It calls through <function>::operator new</function> to 388 obtain new memory when its lists run out. If a client 389 container requests a block larger than a certain threshold 390 size, then the pool is bypassed, and the allocate/deallocate 391 request is passed to <function>::operator new</function> 392 directly. 393 </para> 394 395 <para> 396 Older versions of this class take a boolean template 397 parameter, called <varname>thr</varname>, and an integer template 398 parameter, called <varname>inst</varname>. 399 </para> 400 401 <para> 402 The <varname>inst</varname> number is used to track additional memory 403 pools. The point of the number is to allow multiple 404 instantiations of the classes without changing the semantics at 405 all. All three of 406 </para> 407 408 <programlisting> 409 typedef __pool_alloc<true,0> normal; 410 typedef __pool_alloc<true,1> private; 411 typedef __pool_alloc<true,42> also_private; 412 </programlisting> 413 <para> 414 behave exactly the same way. However, the memory pool for each type 415 (and remember that different instantiations result in different types) 416 remains separate. 417 </para> 418 <para> 419 The library uses <emphasis>0</emphasis> in all its instantiations. If you 420 wish to keep separate free lists for a particular purpose, use a 421 different number. 422 </para> 423 <para>The <varname>thr</varname> boolean determines whether the 424 pool should be manipulated atomically or not. When 425 <varname>thr</varname> = <constant>true</constant>, the allocator 426 is thread-safe, while <varname>thr</varname> = 427 <constant>false</constant>, is slightly faster but unsafe for 428 multiple threads. 429 </para> 430 431 <para> 432 For thread-enabled configurations, the pool is locked with a 433 single big lock. In some situations, this implementation detail 434 may result in severe performance degradation. 435 </para> 436 437 <para> 438 (Note that the GCC thread abstraction layer allows us to provide 439 safe zero-overhead stubs for the threading routines, if threads 440 were disabled at configuration time.) 441 </para> 442 </listitem> 443 444 <listitem> 445 <para> 446 <classname>__mt_alloc</classname> 447 </para> 448 <para> 449 A high-performance fixed-size allocator with 450 exponentially-increasing allocations. It has its own 451 <link linkend="manual.ext.allocator.mt">chapter</link> 452 in the documentation. 453 </para> 454 </listitem> 455 456 <listitem> 457 <para> 458 <classname>bitmap_allocator</classname> 459 </para> 460 <para> 461 A high-performance allocator that uses a bit-map to keep track 462 of the used and unused memory locations. It has its own 463 <link linkend="manual.ext.allocator.bitmap">chapter</link> 464 in the documentation. 465 </para> 466 </listitem> 467 </orderedlist> 468</section> 469 470 471<bibliography xml:id="allocator.biblio"><info><title>Bibliography</title></info> 472 473 474 <biblioentry> 475 <citetitle> 476 ISO/IEC 14882:1998 Programming languages - C++ 477 </citetitle> 478 <abbrev> 479 isoc++_1998 480 </abbrev> 481 <pagenums>20.4 Memory</pagenums> 482 </biblioentry> 483 484 <biblioentry> 485 <title> 486 <link xmlns:xlink="http://www.w3.org/1999/xlink" 487 xlink:href="https://web.archive.org/web/20190622154249/http://www.drdobbs.com/the-standard-librarian-what-are-allocato/184403759"> 488 The Standard Librarian: What Are Allocators Good For? 489 </link> 490 </title> 491 492 <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author> 493 <publisher> 494 <publishername> 495 C/C++ Users Journal 496 </publishername> 497 </publisher> 498 <pubdate>2000-12</pubdate> 499 </biblioentry> 500 501 <biblioentry> 502 <title> 503 <link xmlns:xlink="http://www.w3.org/1999/xlink" 504 xlink:href="http://hoard.org"> 505 The Hoard Memory Allocator 506 </link> 507 </title> 508 509 <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author> 510 </biblioentry> 511 512 <biblioentry> 513 <title> 514 <link xmlns:xlink="http://www.w3.org/1999/xlink" 515 xlink:href="https://people.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf"> 516 Reconsidering Custom Memory Allocation 517 </link> 518 </title> 519 520 <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author> 521 <author><personname><firstname>Ben</firstname><surname>Zorn</surname></personname></author> 522 <author><personname><firstname>Kathryn</firstname><surname>McKinley</surname></personname></author> 523 <copyright> 524 <year>2002</year> 525 <holder>OOPSLA</holder> 526 </copyright> 527 </biblioentry> 528 529 530 <biblioentry> 531 <title> 532 <link xmlns:xlink="http://www.w3.org/1999/xlink" 533 xlink:href="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html"> 534 Allocator Types 535 </link> 536 </title> 537 538 539 <author><personname><firstname>Klaus</firstname><surname>Kreft</surname></personname></author> 540 <author><personname><firstname>Angelika</firstname><surname>Langer</surname></personname></author> 541 <publisher> 542 <publishername> 543 C/C++ Users Journal 544 </publishername> 545 </publisher> 546 </biblioentry> 547 548 <biblioentry> 549 <citetitle>The C++ Programming Language</citetitle> 550 <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author> 551 <copyright> 552 <year>2000</year> 553 <holder/> 554 </copyright> 555 <pagenums>19.4 Allocators</pagenums> 556 <publisher> 557 <publishername> 558 Addison Wesley 559 </publishername> 560 </publisher> 561 </biblioentry> 562 563 <biblioentry> 564 <citetitle>Yalloc: A Recycling C++ Allocator</citetitle> 565 <author><personname><firstname>Felix</firstname><surname>Yen</surname></personname></author> 566 </biblioentry> 567</bibliography> 568 569</section> 570