libstdc++-v3/doc/html/manual/bk01pt03ch20s03.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Implementation</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="
   2       ISO C++
   3     ,
   4       allocator
   5     "><meta name="keywords" content="
   6       ISO C++
   7     ,
   8       library
   9     "><meta name="keywords" content="
  10       ISO C++
  11     ,
  12       runtime
  13     ,
  14       library
  15     "><link rel="home" href="../index.html" title="The GNU C++ Library"><link rel="up" href="mt_allocator.html" title="Chapter 20. The mt_allocator"><link rel="prev" href="bk01pt03ch20s02.html" title="Design Issues"><link rel="next" href="bk01pt03ch20s04.html" title="Single Thread Example"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Implementation</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch20s02.html">Prev</a> </td><th width="60%" align="center">Chapter 20. The mt_allocator</th><td width="20%" align="right"> <a accesskey="n" href="bk01pt03ch20s04.html">Next</a></td></tr></table><hr></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="allocator.mt.impl"></a>Implementation</h2></div></div></div><div class="section" title="Tunable Parameters"><div class="titlepage"><div><div><h3 class="title"><a name="allocator.mt.tune"></a>Tunable Parameters</h3></div></div></div><p>Certain allocation parameters can be modified, or tuned. There
  16 exists a nested <code class="code">struct __pool_base::_Tune</code> that contains all
  17 these parameters, which include settings for
  18 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Alignment</p></li><li class="listitem"><p>Maximum bytes before calling <code class="code">::operator new</code> directly</p></li><li class="listitem"><p>Minimum bytes</p></li><li class="listitem"><p>Size of underlying global allocations</p></li><li class="listitem"><p>Maximum number of supported threads</p></li><li class="listitem"><p>Migration of deallocations to the global free list</p></li><li class="listitem"><p>Shunt for global <code class="code">new</code> and <code class="code">delete</code></p></li></ul></div><p>Adjusting parameters for a given instance of an allocator can only
  19 happen before any allocations take place, when the allocator itself is
  20 initialized. For instance:
  21 </p><pre class="programlisting">
  22 #include &lt;ext/mt_allocator.h&gt;
  23
  24 struct pod
  25 {
  26   int i;
  27   int j;
  28 };
  29
  30 int main()
  31 {
  32   typedef pod value_type;
  33   typedef __gnu_cxx::__mt_alloc&lt;value_type&gt; allocator_type;
  34   typedef __gnu_cxx::__pool_base::_Tune tune_type;
  35
  36   tune_type t_default;
  37   tune_type t_opt(16, 5120, 32, 5120, 20, 10, false);
  38   tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
  39
  40   tune_type t;
  41   t = allocator_type::_M_get_options();
  42   allocator_type::_M_set_options(t_opt);
  43   t = allocator_type::_M_get_options();
  44
  45   allocator_type a;
  46   allocator_type::pointer p1 = a.allocate(128);
  47   allocator_type::pointer p2 = a.allocate(5128);
  48
  49   a.deallocate(p1, 128);
  50   a.deallocate(p2, 5128);
  51
  52   return 0;
  53 }
  54 </pre></div><div class="section" title="Initialization"><div class="titlepage"><div><div><h3 class="title"><a name="allocator.mt.init"></a>Initialization</h3></div></div></div><p>
  55 The static variables (pointers to freelists, tuning parameters etc)
  56 are initialized as above, or are set to the global defaults.
  57 </p><p>
  58 The very first allocate() call will always call the
  59 _S_initialize_once() function.  In order to make sure that this
  60 function is called exactly once we make use of a __gthread_once call
  61 in MT applications and check a static bool (_S_init) in ST
  62 applications.
  63 </p><p>
  64 The _S_initialize() function:
  65 - If the GLIBCXX_FORCE_NEW environment variable is set, it sets the bool
  66   _S_force_new to true and then returns. This will cause subsequent calls to
  67   allocate() to return memory directly from a new() call, and deallocate will
  68   only do a delete() call.
  69 </p><p>
  70 - If the GLIBCXX_FORCE_NEW environment variable is not set, both ST and MT
  71   applications will:
  72   - Calculate the number of bins needed. A bin is a specific power of two size
  73     of bytes. I.e., by default the allocator will deal with requests of up to
  74     128 bytes (or whatever the value of _S_max_bytes is when _S_init() is
  75     called). This means that there will be bins of the following sizes
  76     (in bytes): 1, 2, 4, 8, 16, 32, 64, 128.
  77
  78   - Create the _S_binmap array. All requests are rounded up to the next
  79     "large enough" bin. I.e., a request for 29 bytes will cause a block from
  80     the "32 byte bin" to be returned to the application. The purpose of
  81     _S_binmap is to speed up the process of finding out which bin to use.
  82     I.e., the value of _S_binmap[ 29 ] is initialized to 5 (bin 5 = 32 bytes).
  83 </p><p>
  84   - Create the _S_bin array. This array consists of bin_records. There will be
  85     as many bin_records in this array as the number of bins that we calculated
  86     earlier. I.e., if _S_max_bytes = 128 there will be 8 entries.
  87     Each bin_record is then initialized:
  88     - bin_record-&gt;first = An array of pointers to block_records. There will be
  89       as many block_records pointers as there are maximum number of threads
  90       (in a ST application there is only 1 thread, in a MT application there
  91       are _S_max_threads).
  92       This holds the pointer to the first free block for each thread in this
  93       bin. I.e., if we would like to know where the first free block of size 32
  94       for thread number 3 is we would look this up by: _S_bin[ 5 ].first[ 3 ]
  95
  96     The above created block_record pointers members are now initialized to
  97     their initial values. I.e. _S_bin[ n ].first[ n ] = NULL;
  98 </p><p>
  99 - Additionally a MT application will:
 100   - Create a list of free thread id's. The pointer to the first entry
 101     is stored in _S_thread_freelist_first. The reason for this approach is
 102     that the __gthread_self() call will not return a value that corresponds to
 103     the maximum number of threads allowed but rather a process id number or
 104     something else. So what we do is that we create a list of thread_records.
 105     This list is _S_max_threads long and each entry holds a size_t thread_id
 106     which is initialized to 1, 2, 3, 4, 5 and so on up to _S_max_threads.
 107     Each time a thread calls allocate() or deallocate() we call
 108     _S_get_thread_id() which looks at the value of _S_thread_key which is a
 109     thread local storage pointer. If this is NULL we know that this is a newly
 110     created thread and we pop the first entry from this list and saves the
 111     pointer to this record in the _S_thread_key variable. The next time
 112     we will get the pointer to the thread_record back and we use the
 113     thread_record-&gt;thread_id as identification. I.e., the first thread that
 114     calls allocate will get the first record in this list and thus be thread
 115     number 1 and will then find the pointer to its first free 32 byte block
 116     in _S_bin[ 5 ].first[ 1 ]
 117     When we create the _S_thread_key we also define a destructor
 118     (_S_thread_key_destr) which means that when the thread dies, this
 119     thread_record is returned to the front of this list and the thread id
 120     can then be reused if a new thread is created.
 121     This list is protected by a mutex (_S_thread_freelist_mutex) which is only
 122     locked when records are removed or added to the list.
 123 </p><p>
 124   - Initialize the free and used counters of each bin_record:
 125     - bin_record-&gt;free = An array of size_t. This keeps track of the number
 126       of blocks on a specific thread's freelist in each bin. I.e., if a thread
 127       has 12 32-byte blocks on it's freelists and allocates one of these, this
 128       counter would be decreased to 11.
 129
 130     - bin_record-&gt;used = An array of size_t. This keeps track of the number
 131       of blocks currently in use of this size by this thread. I.e., if a thread
 132       has made 678 requests (and no deallocations...) of 32-byte blocks this
 133       counter will read 678.
 134
 135     The above created arrays are now initialized with their initial values.
 136     I.e. _S_bin[ n ].free[ n ] = 0;
 137 </p><p>
 138   - Initialize the mutex of each bin_record: The bin_record-&gt;mutex
 139     is used to protect the global freelist. This concept of a global
 140     freelist is explained in more detail in the section "A multi
 141     threaded example", but basically this mutex is locked whenever a
 142     block of memory is retrieved or returned to the global freelist
 143     for this specific bin. This only occurs when a number of blocks
 144     are grabbed from the global list to a thread specific list or when
 145     a thread decides to return some blocks to the global freelist.
 146 </p></div><div class="section" title="Deallocation Notes"><div class="titlepage"><div><div><h3 class="title"><a name="allocator.mt.deallocation"></a>Deallocation Notes</h3></div></div></div><p> Notes about deallocation. This allocator does not explicitly
 147 release memory. Because of this, memory debugging programs like
 148 valgrind or purify may notice leaks: sorry about this
 149 inconvenience. Operating systems will reclaim allocated memory at
 150 program termination anyway. If sidestepping this kind of noise is
 151 desired, there are three options: use an allocator, like
 152 <code class="code">new_allocator</code> that releases memory while debugging, use
 153 GLIBCXX_FORCE_NEW to bypass the allocator's internal pools, or use a
 154 custom pool datum that releases resources on destruction.
 155 </p><p>
 156   On systems with the function <code class="code">__cxa_atexit</code>, the
 157 allocator can be forced to free all memory allocated before program
 158 termination with the member function
 159 <code class="code">__pool_type::_M_destroy</code>. However, because this member
 160 function relies on the precise and exactly-conforming ordering of
 161 static destructors, including those of a static local
 162 <code class="code">__pool</code> object, it should not be used, ever, on systems
 163 that don't have the necessary underlying support. In addition, in
 164 practice, forcing deallocation can be tricky, as it requires the
 165 <code class="code">__pool</code> object to be fully-constructed before the object
 166 that uses it is fully constructed. For most (but not all) STL
 167 containers, this works, as an instance of the allocator is constructed
 168 as part of a container's constructor. However, this assumption is
 169 implementation-specific, and subject to change. For an example of a
 170 pool that frees memory, see the following
 171     <a class="link" href="http://gcc.gnu.org/viewcvs/trunk/libstdc++-v3/testsuite/ext/mt_allocator/deallocate_local-6.cc?view=markup" target="_top">
 172     example.</a>
 173 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch20s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="mt_allocator.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="bk01pt03ch20s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Design Issues </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Single Thread Example</td></tr></table></div></body></html>