stl_alloc.h: Deprecate all 'reallocate' memfns.

2002-06-27  Phil Edwards  <pme@gcc.gnu.org>

	* include/bits/stl_alloc.h:  Deprecate all 'reallocate' memfns.
	* docs/html/ext/howto.html:  Update allocator notes.

From-SVN: r55044

libstdc++-v3/ChangeLog

@@ -1,3 +1,8 @@
+2002-06-27  Phil Edwards  <pme@gcc.gnu.org>
+
+	* include/bits/stl_alloc.h:  Deprecate all 'reallocate' memfns.
+	* docs/html/ext/howto.html:  Update allocator notes.
+
 2002-06-26  Benjamin Kosnik  <bkoz@redhat.com>
 
 	* configure.in (INTERFACE): Remove.

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

@@ -37,7 +37,8 @@
 <ul>
    <li><a href="#1">Ropes and trees and hashes, oh my!</a>
    <li><a href="#2">Added members and types</a>
-   <li><a href="#3">Allocators</a>
+   <li><a href="#3">Allocators (versions 3.0, 3.1, 3.2)</a>
+   <li><a href="#6">Allocators (version 3.3)</a>
    <li><a href="#4">Compile-time checks</a>
    <li><a href="#5">LWG Issues</a>
 </ul>
@@ -154,7 +155,7 @@
    </p>
 
 <hr>
-<h2><a name="3">Allocators</a></h2>
+<h2><a name="3">Allocators (versions 3.0, 3.1, 3.2)</a></h2>
    <p>Thread-safety, space efficiency, high speed, portability... this is a
       mess.  Where to begin?
    </p>
@@ -220,17 +221,18 @@
    </p>
    <h3>Available allocators in namespace std</h3>
    <p>First I'll describe the situation as it exists for the code which
-      was released in GCC 3.1.  Then I'll
+      was released in GCC 3.1 and 3.2.  Then I'll describe the differences
-      describe the differences for 3.0.x, which will not change much in
+      for 3.0.  The allocator classes also have source documentation,
-      this respect.
+      which is described <a href="../documentation.html#4">here</a> (you
+      will need to retrieve the maintainer-level docs, as almost none of
+      these entities are in the ISO standard).
    </p>
    <p>As a general rule of thumb, users are not allowed to use names which
       begin with an underscore.  This means that to be portable between
       compilers, none of the following may be used in your program directly.
       (If you decide to be unportable, then you're free do do what you want,
       but it's not our fault if stuff breaks.)  They are presented here for
-      information for maintainers and contributors in addition to users, but
+      information for maintainers and contributors in addition to users.
-      we will probably make them available for users in 3.2 somehow.
    </p>
    <p>These classes are always available:
      <ul>
@@ -301,7 +303,7 @@
      <li><code>__single_client_alloc</code> are all typedef'd to
          <code>__malloc_alloc_template</code>.
      <li><code>__default_alloc_template</code> is no longer available.
-         At all.  Anywhere.  <!-- might change? -->
+         At all.  Anywhere.
      </ol>
    </p>
    <h3>Writing your own allocators</h3>
@@ -359,7 +361,13 @@
       can affect the 3.0.x allocators.  Do not use them.  Those macros have
       been completely removed for 3.1.
    </p>
-   <p>More notes as we remember them...
+   <p>Return <a href="#top">to top of page</a> or
+      <a href="../faq/index.html">to the FAQ</a>.
+   </p>
+
+<hr>
+<h2><a name="6">Allocators (version 3.3)</a></h2>
+   <p>Changes are coming...
    </p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
@@ -540,6 +548,7 @@
    </dl></p>
    <p>Return <a href="#top">to top of page</a> or
       <a href="../faq/index.html">to the FAQ</a>.
+   </p>
 
 
 <!-- ####################################################### -->

libstdc++-v3/include/bits/stl_alloc.h

@@ -74,6 +74,10 @@
  *  into a "standard" one.
  *  @endif
  *
+ *  @note The @c reallocate member functions have been deprecated for 3.2
+ *        and will be removed in 3.3.  You must define @c _GLIBCPP_DEPRECATED
+ *        to make this visible in 3.2; see c++config.h.
+ *
  *  The canonical description of these classes is in docs/html/ext/howto.html
  *  or online at http://gcc.gnu.org/onlinedocs/libstdc++/ext/howto.html#3
 */
@@ -122,7 +126,9 @@ namespace std
     {
     private:
       static void* _S_oom_malloc(size_t);
+#ifdef _GLIBCPP_DEPRECATED
       static void* _S_oom_realloc(void*, size_t);
+#endif
       static void (* __malloc_alloc_oom_handler)();
 
     public:
@@ -138,6 +144,7 @@ namespace std
       deallocate(void* __p, size_t /* __n */)
       { free(__p); }
 
+#ifdef _GLIBCPP_DEPRECATED
       static void*
       reallocate(void* __p, size_t /* old_sz */, size_t __new_sz)
       {
@@ -146,6 +153,7 @@ namespace std
           __result = _S_oom_realloc(__p, __new_sz);
         return __result;
       }
+#endif
 
       static void (* __set_malloc_handler(void (*__f)()))()
       {
@@ -161,7 +169,8 @@ namespace std
 
   template<int __inst>
     void*
-    __malloc_alloc_template<__inst>::_S_oom_malloc(size_t __n)
+    __malloc_alloc_template<__inst>::
+    _S_oom_malloc(size_t __n)
     {
       void (* __my_malloc_handler)();
       void* __result;
@@ -178,6 +187,7 @@ namespace std
         }
     }
 
+#ifdef _GLIBCPP_DEPRECATED
   template<int __inst>
     void*
     __malloc_alloc_template<__inst>::
@@ -197,6 +207,7 @@ namespace std
             return(__result);
         }
     }
+#endif
 
 
   // Determines the underlying allocator choice for the node allocator.
@@ -278,6 +289,7 @@ namespace std
         _Alloc::deallocate(__real_p, __n + (int) _S_extra);
       }
 
+#ifdef _GLIBCPP_DEPRECATED
       static void*
       reallocate(void* __p, size_t __old_sz, size_t __new_sz)
       {
@@ -289,6 +301,7 @@ namespace std
         *(size_t*)__result = __new_sz;
         return __result + (int) _S_extra;
       }
+#endif
     };
 
 
@@ -429,8 +442,10 @@ namespace std
           }
       }
 
+#ifdef _GLIBCPP_DEPRECATED
       static void*
       reallocate(void* __p, size_t __old_sz, size_t __new_sz);
+#endif
     };
 
 
@@ -560,6 +575,7 @@ namespace std
     }
 
 
+#ifdef _GLIBCPP_DEPRECATED
   template<bool threads, int inst>
     void*
     __default_alloc_template<threads, inst>::
@@ -578,6 +594,7 @@ namespace std
       deallocate(__p, __old_sz);
       return(__result);
     }
+#endif
 
   template<bool __threads, int __inst>
     _STL_mutex_lock