1 <sect1 id="manual.util.memory.allocator" xreflabel="Allocator">
2 <?dbhtml filename="allocator.html"?>
15 <title>Allocators</title>
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>)
27 <sect2 id="allocator.req" xreflabel="allocator.req">
28 <title>Requirements</title>
31 The C++ standard only gives a few directives in this area:
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
47 The default <type>Allocator</type> argument of every
48 container-of-T is <classname>allocator<T></classname>.
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
59 T* allocate (size_type n, const void* hint = 0);
60 void deallocate (T* p, size_type n);
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.)
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>
84 Complete details cam be found in the C++ standard, look in
85 <constant>[20.4 Memory]</constant>.
90 <sect2 id="allocator.design_issues" xreflabel="allocator.design_issues">
91 <title>Design Issues</title>
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>.
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>.
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.
141 <sect2 id="allocator.impl" xreflabel="allocator.impl">
142 <title>Implementation</title>
145 <title>Interface Design</title>
148 The only allocator interface that
149 is support 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.
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.
162 The base class that <classname>allocator</classname> is derived from
163 may not be user-configurable.
169 <title>Selecting Default Allocation Policy</title>
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
179 Three synthetic benchmarks have been created that provide data
180 that is used to compare different C++ allocators. These tests are:
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>
201 Insertion and erasure in a multi-threaded environment.
204 This test shows the ability of the allocator to reclaim memory
205 on a pre-thread basis, as well as measuring thread contention
206 for memory resources.
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>.
214 A threaded producer/consumer model.
218 <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/sequence.cc?view=markup">sequence</ulink>
220 <ulink url="http://gcc.gnu.org/viewcvs/trunk/libstdc%2B%2B-v3/testsuite/performance/23_containers/producer_consumer/associative.cc?view=markup">associative</ulink>
227 The current default choice for
228 <classname>allocator</classname> is
229 <classname>__gnu_cxx::new_allocator</classname>.
235 <title>Disabling Memory Caching</title>
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
248 This can be confusing.
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>.
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.
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...).
288 <sect2 id="allocator.using" xreflabel="allocator.using">
289 <title>Using a Specific Allocator</title>
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:
299 std::list <int, __gnu_cxx::malloc_allocator<int> > malloc_list;</programlisting>
301 Likewise, a debugging form of whichever allocator is currently in use:
304 std::deque <int, __gnu_cxx::debug_allocator<std::allocator<int> > > debug_deque;
308 <sect2 id="allocator.custom" xreflabel="allocator.custom">
309 <title>Custom Allocators</title>
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.
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>.
326 <sect2 id="allocator.ext" xreflabel="allocator.ext">
327 <title>Extension Allocators</title>
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.
340 More details on each of these extension allocators follows.
345 <classname>new_allocator</classname>
348 Simply wraps <function>::operator new</function>
349 and <function>::operator delete</function>.
354 <classname>malloc_allocator</classname>
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).
366 <classname>array_allocator</classname>
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.
383 <classname>debug_allocator</classname>
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.
396 <classname>throw_allocator</classname>
399 Includes memory tracking and marking abilities as well as hooks for
400 throwing exceptions at configurable intervals (including random,
406 <classname>__pool_alloc</classname>
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>
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>.
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
433 typedef __pool_alloc<true,0> normal;
434 typedef __pool_alloc<true,1> private;
435 typedef __pool_alloc<true,42> also_private;
438 behave exactly the same way. However, the memory pool for each type
439 (and remember that different instantiations result in different types)
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
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 is thread-safe, while <varname>thr</varname> =
451 <constant>false</constant>, and is slightly faster but unsafe for
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.
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.)
470 <classname>__mt_alloc</classname>
473 A high-performance fixed-size allocator with
474 exponentially-increasing allocations. It has its own
475 documentation, found <ulink
476 url="../ext/mt_allocator.html">here</ulink>.
482 <classname>bitmap_allocator</classname>
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 <ulink
488 url="../ext/ballocator_doc.html">here</ulink>.
495 <bibliography id="allocator.biblio" xreflabel="allocator.biblio">
496 <title>Bibliography</title>
500 ISO/IEC 14882:1998 Programming languages - C++
506 <pagenums>20.4 Memory</pagenums>
510 <title>The Standard Librarian: What Are Allocators Good
518 <firstname>Matt</firstname>
519 <surname>Austern</surname>
529 <ulink url="http://www.cuj.com/documents/s=8000/cujcexp1812austern/">
535 <title>The Hoard Memory Allocator</title>
542 <firstname>Emery</firstname>
543 <surname>Berger</surname>
547 <ulink url="http://www.cs.umass.edu/~emery/hoard/">
553 <title>Reconsidering Custom Memory Allocation</title>
560 <firstname>Emery</firstname>
561 <surname>Berger</surname>
564 <firstname>Ben</firstname>
565 <surname>Zorn</surname>
568 <firstname>Kathryn</firstname>
569 <surname>McKinley</surname>
574 <holder>OOPSLA</holder>
578 <ulink url="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf">
585 <title>Allocator Types</title>
592 <firstname>Klaus</firstname>
593 <surname>Kreft</surname>
596 <firstname>Angelika</firstname>
597 <surname>Langer</surname>
607 <ulink url="http://www.langer.camelot.de/Articles/C++Report/Allocators/Allocators.html">
613 <title>The C++ Programming Language</title>
620 <firstname>Bjarne</firstname>
621 <surname>Stroustrup</surname>
627 <pagenums>19.4 Allocators</pagenums>
637 <title>Yalloc: A Recycling C++ Allocator</title>
644 <firstname>Felix</firstname>
645 <surname>Yen</surname>
653 <ulink url="http://home.earthlink.net/~brimar/yalloc/">