mt_allocator.html: Add docs for _Tune.

2004-07-13  Benjamin Kosnik  <bkoz@redhat.com>

	* docs/html/ext/mt_allocator.html: Add docs for _Tune.
	* include/ext/mt_allocator.h (__mt_alloc::_S_get_options): Make public.
	(__mt_alloc::_S_set_options): Same.
	Add to comments.

2004-07-13  Benjamin Kosnik  <bkoz@redhat.com>

	* acinclude.m4 (GLIBCXX_ENABLE_ALLOCATOR): Add allocator defaults
	for linux.
	* configure: Regenerated.

From-SVN: r84674

libstdc++-v3/ChangeLog

@@ -1,3 +1,16 @@
+2004-07-13  Benjamin Kosnik  <bkoz@redhat.com>
+
+	* docs/html/ext/mt_allocator.html: Add docs for _Tune.
+	* include/ext/mt_allocator.h (__mt_alloc::_S_get_options): Make public.
+	(__mt_alloc::_S_set_options): Same.
+	Add to comments.
+
+2004-07-13  Benjamin Kosnik  <bkoz@redhat.com>
+
+	* acinclude.m4 (GLIBCXX_ENABLE_ALLOCATOR): Add allocator defaults
+	for linux.
+	* configure: Regenerated.
+
 2004-07-13  Paolo Carlini  <pcarlini@suse.de>
 
 	* testsuite/22_locale/locale/cons/12658_thread.cc: Move/rename

libstdc++-v3/acinclude.m4

@@ -1163,13 +1163,17 @@ AC_DEFUN([GLIBCXX_ENABLE_ALLOCATOR], [
      enable_libstdcxx_allocator=auto
   fi
 
-  # Either a known package, or "auto"
+  # Either a known package, or "auto". Auto implies the default choice
+  # for a particular platform.
   enable_libstdcxx_allocator_flag=$enable_libstdcxx_allocator
 
   # Probe for host-specific support if no specific model is specified.
   # Default to "new".
   if test $enable_libstdcxx_allocator_flag = auto; then
     case ${target_os} in
+      linux* | gnu* | kfreebsd*-gnu | knetbsd*-gnu)
+        enable_libstdcxx_allocator_flag=mt
+        ;;
       *)
         enable_libstdcxx_allocator_flag=new
         ;;

libstdc++-v3/docs/html/ext/mt_allocator.html

@@ -53,6 +53,61 @@ The aim of this document is to describe - from a application point of
 view - the "inner workings" of the allocator.
 </p>
 
+<h3 class="left">
+  <a name="init">Tunable parameters</a>
+</h3>
+
+<p>Certain allocation parameters can be modified on a per-type
+basis. There exists a nested <pre>struct _Tune</pre> that contains all
+these parameters, which include settings for
+</p>
+   <ul>
+     <li>Alignment </li>
+     <li>Maximum bytes before calling <code>::operator new</code> directly</li>
+     <li>Minimum bytes</li>
+     <li>Size of underlying global allocations</li>
+     <li>Maximum number of supported threads</li>
+     <li>Migration of deallocations to the global free list</li>
+     <li>Shunt for global <code>new</code> and <code>delete</code></li>
+   </ul>
+<p>Adjusting parameters for a given instance of an allocator can only
+happen before any allocations take place, when the allocator itself is
+initialized. For instance:
+</p>
+<pre>
+#include &lt;ext/mt_allocator.h&gt;
+
+struct pod
+{
+  int i;
+  int j;
+};
+
+int main()
+{
+  typedef pod value_type;
+  typedef __gnu_cxx::__mt_alloc&lt;value_type&gt; allocator_type;
+  typedef allocator_type::_Tune tune_type;
+
+  tune_type t_default;
+  tune_type t_opt(16, 5120, 32, 5120, 20, 10, false);
+  tune_type t_single(16, 5120, 32, 5120, 1, 10, false);
+
+  tune_type t;
+  t = allocator_type::_S_get_options();  
+  allocator_type::_S_set_options(t_opt);
+  t = allocator_type::_S_get_options();  
+
+  allocator_type a;
+  allocator_type::pointer p1 = a.allocate(128);
+  allocator_type::pointer p2 = a.allocate(5128);
+
+  a.deallocate(p1, 128);
+  a.deallocate(p2, 5128);
+
+  return 0;
+}
+</pre>
 
 <h3 class="left">
   <a name="init">Initialization</a>
@@ -60,14 +115,9 @@ view - the "inner workings" of the allocator.
 
 <p>
 The static variables (pointers to freelists, tuning parameters etc)
-are initialized to their default values at file scope, i.e.:
+are initialized as above, or are set to the global defaults.
 </p>
 
-<pre>
-  template&lt;typename _Tp&gt; size_t
-  __mt_alloc&lt;_Tp&gt;::_S_freelist_headroom = 10;
-</pre>
-
 <p>
 The very first allocate() call will always call the _S_init() function. 
 In order to make sure that this function is called exactly once we make use

libstdc++-v3/include/ext/mt_allocator.h

@@ -139,8 +139,12 @@ namespace __gnu_cxx
 	// See http://gcc.gnu.org/ml/libstdc++/2001-07/msg00077.html
 	size_t 	_M_chunk_size;
 
-	// The maximum number of supported threads. Our Linux 2.4.18
+	// The maximum number of supported threads. For
-	// reports 4070 in /proc/sys/kernel/threads-max
+	// single-threaded operation, use one. Maximum values will
+	// vary depending on details of the underlying system. (For
+	// instance, Linux 2.4.18 reports 4070 in
+	// /proc/sys/kernel/threads-max, while Linux 2.6.6 reports
+	// 65534)
 	size_t 	_M_max_threads;
 
 	// Each time a deallocation occurs in a threaded application
@@ -172,6 +176,17 @@ namespace __gnu_cxx
 	{ }
       };
 
+      static const _Tune
+      _S_get_options()
+      { return _S_options; }
+
+      static void
+      _S_set_options(_Tune __t)
+      { 
+	if (!_S_init)
+	  _S_options = __t;
+      }
+
     private:
       // We need to create the initial lists and set up some variables
       // before we can answer to the first request for memory.
@@ -186,17 +201,6 @@ namespace __gnu_cxx
       // Configuration options.
       static _Tune 	       		_S_options;
 
-      static const _Tune
-      _S_get_options()
-      { return _S_options; }
-
-      static void
-      _S_set_options(_Tune __t)
-      { 
-	if (!_S_init)
-	  _S_options = __t;
-      }
-
       // Using short int as type for the binmap implies we are never
       // caching blocks larger than 65535 with this allocator
       typedef unsigned short int        _Binmap_type;