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 choice of base class that <classname>allocator</classname> 158 is derived from is fixed at the time when GCC is built, 159 and the different choices are not ABI compatible. 160</para> 161 162 </section> 163 164 <section xml:id="allocator.default"><info><title>Selecting Default Allocation Policy</title></info> 165 166 <para> 167 It's difficult to pick an allocation strategy that will provide 168 maximum utility, without excessively penalizing some behavior. In 169 fact, it's difficult just deciding which typical actions to measure 170 for speed. 171 </para> 172 173 <para> 174 Three synthetic benchmarks have been created that provide data 175 that is used to compare different C++ allocators. These tests are: 176 </para> 177 178 <orderedlist> 179 <listitem> 180 <para> 181 Insertion. 182 </para> 183 <para> 184 Over multiple iterations, various STL container 185 objects have elements inserted to some maximum amount. A variety 186 of allocators are tested. 187 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> 188 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> 189 containers. 190 </para> 191 192 </listitem> 193 194 <listitem> 195 <para> 196 Insertion and erasure in a multi-threaded environment. 197 </para> 198 <para> 199 This test shows the ability of the allocator to reclaim memory 200 on a per-thread basis, as well as measuring thread contention 201 for memory resources. 202 Test source 203 <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>. 204 </para> 205 </listitem> 206 207 <listitem> 208 <para> 209 A threaded producer/consumer model. 210 </para> 211 <para> 212 Test source for 213 <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> 214 and 215 <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> 216 containers. 217 </para> 218 </listitem> 219 </orderedlist> 220 221 <para> 222 Since GCC 12 the default choice for 223 <classname>allocator</classname> is 224 <classname>std::__new_allocator</classname>. 225 Before GCC 12 it was the <classname>__gnu_cxx::new_allocator</classname> 226 extension (which has identical behaviour). 227 </para> 228 229 </section> 230 231 <section xml:id="allocator.caching"><info><title>Disabling Memory Caching</title></info> 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 <para> 321 Since C++11 the minimal interface require for an allocator is 322 much smaller, as <classname>std::allocator_traits</classname> 323 can provide default for much of the interface. 324 </para> 325 326 327</section> 328 329<section xml:id="allocator.ext"><info><title>Extension Allocators</title></info> 330 331 332 <para> 333 Several other allocators are provided as part of this 334 implementation. The location of the extension allocators and their 335 names have changed, but in all cases, functionality is 336 equivalent. Starting with gcc-3.4, all extension allocators are 337 standard style. Before this point, SGI style was the norm. Because of 338 this, the number of template arguments also changed. 339 <xref linkend="table.extension_allocators"/> tracks the changes. 340 </para> 341 342 <para> 343 More details on each of these extension allocators follows. 344 </para> 345 <orderedlist> 346 <listitem> 347 <para> 348 <classname>new_allocator</classname> 349 </para> 350 <para> 351 Simply wraps <function>::operator new</function> 352 and <function>::operator delete</function>. 353 </para> 354 </listitem> 355 <listitem> 356 <para> 357 <classname>malloc_allocator</classname> 358 </para> 359 <para> 360 Simply wraps <function>malloc</function> and 361 <function>free</function>. There is also a hook for an 362 out-of-memory handler (for 363 <function>new</function>/<function>delete</function> this is 364 taken care of elsewhere). 365 </para> 366 </listitem> 367 <listitem> 368 <para> 369 <classname>debug_allocator</classname> 370 </para> 371 <para> 372 A wrapper around an arbitrary allocator <classname>A</classname>. 373 It passes on slightly increased size requests to <classname>A</classname>, 374 and uses the extra memory to store size information. 375 When a pointer is passed 376 to <function>deallocate()</function>, the stored size is 377 checked, and <function>assert()</function> is used to 378 guarantee they match. 379 </para> 380 </listitem> 381 <listitem> 382 <para> 383 <classname>throw_allocator</classname> 384 </para> 385 <para> 386 Includes memory tracking and marking abilities as well as hooks for 387 throwing exceptions at configurable intervals (including random, 388 all, none). 389 </para> 390 </listitem> 391 <listitem> 392 <para> 393 <classname>__pool_alloc</classname> 394 </para> 395 <para> 396 A high-performance, single pool allocator. The reusable 397 memory is shared among identical instantiations of this type. 398 It calls through <function>::operator new</function> to 399 obtain new memory when its lists run out. If a client 400 container requests a block larger than a certain threshold 401 size, then the pool is bypassed, and the allocate/deallocate 402 request is passed to <function>::operator new</function> 403 directly. 404 </para> 405 406 <para> 407 For thread-enabled configurations, the pool is locked with a 408 single big lock. In some situations, this implementation detail 409 may result in severe performance degradation. 410 </para> 411 412 <para> 413 (Note that the GCC thread abstraction layer allows us to provide 414 safe zero-overhead stubs for the threading routines, if threads 415 were disabled at configuration time.) 416 </para> 417 </listitem> 418 419 <listitem> 420 <para> 421 <classname>__mt_alloc</classname> 422 </para> 423 <para> 424 A high-performance fixed-size allocator with 425 exponentially-increasing allocations. It has its own 426 <link linkend="manual.ext.allocator.mt">chapter</link> 427 in the documentation. 428 </para> 429 </listitem> 430 431 <listitem> 432 <para> 433 <classname>bitmap_allocator</classname> 434 </para> 435 <para> 436 A high-performance allocator that uses a bit-map to keep track 437 of the used and unused memory locations. It has its own 438 <link linkend="manual.ext.allocator.bitmap">chapter</link> 439 in the documentation. 440 </para> 441 </listitem> 442 </orderedlist> 443</section> 444 445 446<bibliography xml:id="allocator.biblio"><info><title>Bibliography</title></info> 447 448 449 <biblioentry> 450 <citetitle> 451 ISO/IEC 14882:1998 Programming languages - C++ 452 </citetitle> 453 <abbrev> 454 isoc++_1998 455 </abbrev> 456 <pagenums>20.4 Memory</pagenums> 457 </biblioentry> 458 459 <biblioentry> 460 <title> 461 <link xmlns:xlink="http://www.w3.org/1999/xlink" 462 xlink:href="https://web.archive.org/web/20190622154249/http://www.drdobbs.com/the-standard-librarian-what-are-allocato/184403759"> 463 The Standard Librarian: What Are Allocators Good For? 464 </link> 465 </title> 466 467 <author><personname><firstname>Matt</firstname><surname>Austern</surname></personname></author> 468 <publisher> 469 <publishername> 470 C/C++ Users Journal 471 </publishername> 472 </publisher> 473 <pubdate>2000-12</pubdate> 474 </biblioentry> 475 476 <biblioentry> 477 <title> 478 <link xmlns:xlink="http://www.w3.org/1999/xlink" 479 xlink:href="http://hoard.org"> 480 The Hoard Memory Allocator 481 </link> 482 </title> 483 484 <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author> 485 </biblioentry> 486 487 <biblioentry> 488 <title> 489 <link xmlns:xlink="http://www.w3.org/1999/xlink" 490 xlink:href="https://people.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf"> 491 Reconsidering Custom Memory Allocation 492 </link> 493 </title> 494 495 <author><personname><firstname>Emery</firstname><surname>Berger</surname></personname></author> 496 <author><personname><firstname>Ben</firstname><surname>Zorn</surname></personname></author> 497 <author><personname><firstname>Kathryn</firstname><surname>McKinley</surname></personname></author> 498 <copyright> 499 <year>2002</year> 500 <holder>OOPSLA</holder> 501 </copyright> 502 </biblioentry> 503 504 505 <biblioentry> 506 <title> 507 <link xmlns:xlink="http://www.w3.org/1999/xlink" 508 xlink:href="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html"> 509 Allocator Types 510 </link> 511 </title> 512 513 514 <author><personname><firstname>Klaus</firstname><surname>Kreft</surname></personname></author> 515 <author><personname><firstname>Angelika</firstname><surname>Langer</surname></personname></author> 516 <publisher> 517 <publishername> 518 C/C++ Users Journal 519 </publishername> 520 </publisher> 521 </biblioentry> 522 523 <biblioentry> 524 <citetitle>The C++ Programming Language</citetitle> 525 <author><personname><firstname>Bjarne</firstname><surname>Stroustrup</surname></personname></author> 526 <copyright> 527 <year>2000</year> 528 <holder/> 529 </copyright> 530 <pagenums>19.4 Allocators</pagenums> 531 <publisher> 532 <publishername> 533 Addison Wesley 534 </publishername> 535 </publisher> 536 </biblioentry> 537 538 <biblioentry> 539 <citetitle>Yalloc: A Recycling C++ Allocator</citetitle> 540 <author><personname><firstname>Felix</firstname><surname>Yen</surname></personname></author> 541 </biblioentry> 542</bibliography> 543 544</section> 545