From 7145a3ddd9a4db0d8761b324f19c5dea1cb27500 Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Wed, 28 Nov 2001 00:02:04 +0000 Subject: [PATCH] explanations.html: New section, empty for now. 2001-11-27 Phil Edwards * docs/html/explanations.html: New section, empty for now. * docs/html/17_intro/howto.html: Cleanup. Move unrelated link... * docs/html/23_containers/howto.html: ...to here. Break up and rewrap threading discussion to emphasize warning. Move malloc text... * docs/html/ext/howto.html: ...to here. New section. Describe allocators and __USE_MALLOC effects. * docs/html/ext/sgiexts.html: Mention their code. From-SVN: r47391 --- libstdc++-v3/ChangeLog | 10 + libstdc++-v3/docs/html/17_intro/howto.html | 7 +- .../docs/html/23_containers/howto.html | 40 ++-- libstdc++-v3/docs/html/explanations.html | 9 + libstdc++-v3/docs/html/ext/howto.html | 189 +++++++++++++++++- libstdc++-v3/docs/html/ext/sgiexts.html | 5 +- 6 files changed, 236 insertions(+), 24 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 8ecca20ce4f..0f58b3cf82b 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,13 @@ +2001-11-27 Phil Edwards + + * docs/html/explanations.html: New section, empty for now. + * docs/html/17_intro/howto.html: Cleanup. Move unrelated link... + * docs/html/23_containers/howto.html: ...to here. Break up and + rewrap threading discussion to emphasize warning. Move malloc text... + * docs/html/ext/howto.html: ...to here. New section. Describe + allocators and __USE_MALLOC effects. + * docs/html/ext/sgiexts.html: Mention their code. + 2001-11-24 Joseph S. Myers * docs/doxygen/maint.cfg.in, docs/doxygen/user.cfg.in, diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index 3dce6f912a3..abbeb814d50 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -74,7 +74,7 @@

All normal disclaimers aside, multithreaded C++ application are only supported when libstdc++ and all user code was built with - compilers which report (via gcc/g++ -v) the same thread + compilers which report (via gcc/g++ -v ) the same thread model and that model is not single. As long as your final application is actually single-threaded, then it should be safe to mix user code built with a thread model of @@ -89,7 +89,7 @@

When you link a multithreaded application, you will probably need to add a library or flag to g++. This is a very - non-standardized area of gcc across ports. Some ports support a + non-standardized area of GCC across ports. Some ports support a special flag (the spelling isn't even standardized yet) to add all required macros to a compilation (if any such flags are required then you must provide the flag for all compilations not @@ -135,9 +135,6 @@ This message inspired a recent updating of issues with threading and the SGI STL library. It also contains some example POSIX-multithreaded STL code. -

  • - Here is an early analysis of why __USE_MALLOC should be disabled - for the 3.0 release of libstdc++. (A large selection of links to older messages has been removed; many of the messages from 1999 were lost in a disk crash, and the few diff --git a/libstdc++-v3/docs/html/23_containers/howto.html b/libstdc++-v3/docs/html/23_containers/howto.html index 29c72185041..7684bcab5ae 100644 --- a/libstdc++-v3/docs/html/23_containers/howto.html +++ b/libstdc++-v3/docs/html/23_containers/howto.html @@ -244,14 +244,22 @@

    The STL implementation is currently configured to use the high-speed caching memory allocator. If you absolutely think - you must change this on a global basis for your platform to - better support multi-threading, then please consult all - commentary in include/bits/c++config. (Explicit warning since - so many people post after getting confused while attempting - this:) Adding -D__USE_MALLOC on the command line is not a good - idea. Related to threading or otherwise, the current - recommendation is that users not add any macro defines on the - command line to enable features out of libstdc++-v3. There is + you must change this on a global basis for your platform to better + support multi-threading, then please consult all commentary in + include/bits/stl_alloc.h and the allocators link below. +

    +

    (Explicit warning since so many people get confused while + attempting this:) +

    +

    Adding -D__USE_MALLOC on the command + line is almost certainly a bad idea. Memory efficiency is + almost guaranteed to suffer as a result; this is + why + we disabled it for 3.0 in the first place. +

    +

    Related to threading or otherwise, the current recommendation is + that users not add any macro defines on the command line to remove or + otherwise disable features of libstdc++-v3. There is no condition under which it will help you without causing other issues to perhaps raise up (possible linkage/ABI problems). In particular, __USE_MALLOC should only be added to a libstdc++-v3 @@ -259,22 +267,22 @@ action is cautioned against), and the entire library should be rebuilt. If you do not, then you might be violating the one-definition rule of C/C++ and you might cause yourself untold - problems. If you find any platform where gcc reports a - threading model other than single and where libstdc++-v3 builds + problems. +

    +
    + If you find any platform where gcc reports a + threading model other than single, and where libstdc++-v3 builds a buggy container allocator when used with threads unless you define __USE_MALLOC, we want to hear about it ASAP. In the past, correctness was the main reason people were led to believe that they should define __USE_MALLOC when using threads.

    -

    There is a better way (not standardized yet): It is possible to +

    There is a better way (not standardized yet): It is possible to force the malloc-based allocator on a per-case-basis for some application code. The library team generally believes that this is a better way to tune an application for high-speed using this - implementation of the STL. Here is one possible example - displaying the forcing of the malloc-based allocator over the - typically higher-speed default allocator: - 

    -      std::list <my_type, std::__malloc_alloc_template<0> >  my_malloc_based_list;
    + implementation of the STL. There is + more information on allocators here.

    Return to top of page or to the FAQ. diff --git a/libstdc++-v3/docs/html/explanations.html b/libstdc++-v3/docs/html/explanations.html index e5cdbce274c..164a5a1cf8e 100644 --- a/libstdc++-v3/docs/html/explanations.html +++ b/libstdc++-v3/docs/html/explanations.html @@ -61,6 +61,15 @@ design

    +
    +

    Internal Allocators

     +

    +

    +

    Return to the top of the page or + to the homepage. +

    + +
    diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html index e8663815540..53c29498d00 100644 --- a/libstdc++-v3/docs/html/ext/howto.html +++ b/libstdc++-v3/docs/html/ext/howto.html @@ -143,8 +143,193 @@

    Allocators

    -

    This will be blank for a while. It will describe all of the different - memory allocators, most inherited from SGI's code. Input is solicited. +

    Thread-safety, space efficiency, high speed, portability... this is a + mess. Where to begin? +

    +

    The Rules

    +

    The C++ standard only gives a few directives in this area: +

      +
    • When you add elements to a container, and the container must allocate + more memory to hold them, the container makes the request via its + Allocator template parameter. This includes adding + char's to the string class, which acts as a regular STL container + in this respect. +
    • The default Allocator of every container-of-T is + std::allocator<T>. +
    • The interface of the allocator<T> class is + extremely simple. It has about 20 public declarations (nested + typedefs, member functions, etc), but the two which concern us most + are: + 
      +      T*    allocate   (size_type n, const void* hint = 0);
+      void  deallocate (T* p, size_type n);
      + (This is a simplicifcation; the real signatures use nested typedefs.) + The "n" arguments in both those functions is a + count of the number of T's to allocate space for, + not their total size. +
    • "The storage is obtained by calling + ::operator new(size_t), but it is unspecified when or + how often this function is called. The use of hint + is unspecified, but intended as an aid to locality if an + implementation so desires." [20.4.1.1]/6 +
    +

    +

    Problems and Possibilities

    +

    The easiest way of fulfilling the requirements is to call operator new + each time a container needs memory, and to call operator delete each + time the container releases memory. BUT + this + method is horribly slow. +

    +

    Or we can keep old memory around, and reuse it in a pool to save time. + The old libstdc++-v2 used a memory pool, and so do we. As of 3.0, + it's + on by default. The pool is shared among all the containers in the + program: when your program's std::vector<int> gets cut in half + and frees a bunch of its storage, that memory can be reused by the + private std::list<WonkyWidget> brought in from a KDE library + that you linked against. And we don't have to call operator's new and + delete to pass the memory on, ether, which is a speed bonus. + BUT... +

    +

    What about threads? No problem: in a threadsafe environment, the + memory pool is manipulated atomically, so you can grow a container in + one thread and shrink it in another, etc. BUT what + if threads in libstdc++-v3 aren't set up properly? + That's been answered already. +

    +

    BUT what if you want to use your own allocator? What + if you plan on using a runtime-loadable version of malloc() which uses + shared telepathic anonymous mmap'd sections serializable over a + network, so that memory requests should go through malloc? + And what if you need to debug it? +

    +

    Well then: +

    +

    Available allocators in namespace std

    +

    First I'll describe the situation as it exists for the code which will + be released in GCC 3.1. This situation is extremely fluid. Then I'll + describe the differences for 3.0.x, which will not change much in + this respect. +

    +

    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 + we will probably make them available for users in 3.1 somehow. +

    +

    These classes are always available: +

      +
    • __new_alloc simply wraps ::operator new + and ::operator delete. +
    • __malloc_alloc_template<int inst> simply wraps + malloc and free. There is also a hook + for an out-of-memory handler (for new/delete this is taken care of + elsewhere). The inst parameter is described below. + This class was called malloc_alloc in earlier versions. +
    • allocator<T> has already been described; it is + The Standard Allocator for instances of T. It uses the internal + __alloc typedef (see below) to satisy its requests. +
    • __simple_alloc<T,A> is a wrapper around another + allocator, A, which itself is an allocator for instances of T. + This is primarily used in an internal "allocator traits" + class which helps encapsulate the different styles of allocators. +
    • __debug_alloc<A> is also a wrapper around an + arbitrary allocator A. It passes on slightly increased size + requests to A, and uses the extra memory to store size information. + When a pointer is passed to deallocate(), the stored + size is checked, and assert() is used to guarantee they match. +
    • __allocator<T,A> is an adaptor. Many of these + allocator classes have a consistent yet non-standard interface. + Such classes can be changed to a conforming interface with this + wrapper: __allocator<T, __alloc> is thus the + same as allocator<T>. +
    +

    +

    An internal typedef, __mem_interface , is defined to be + __new_alloc by default. +

    +

    Normally, + __default_alloc_template<bool thr, int inst> + is also available. This is the high-speed pool, called the default + node allocator. The reusable memory is shared among identical + instantiations of + this type. It calls through __mem_interface to obtain + new memory when its lists run out. If a client container requests a + block larger than a certain threshold size, then the pool is bypassed, + and the allocate/deallocate request is passed to + __mem_interface directly. +

    +

    Its inst parameter is described below. The + thr boolean determines whether the pool should be + manipulated atomically or not. Two typedefs are provided: + __alloc is defined as this node allocator with thr=true, + and therefore is threadsafe, while __single_client_alloc + defines thr=false, and is slightly faster but unsafe for multiple + threads. +

    +

    (Note that the GCC thread abstraction layer allows us to provide safe + zero-overhead stubs for the threading routines, if threads were + disabled at configuration time. In this situation, + __alloc should not be noticably slower than + __single_client_alloc.) +

    +

    A cannon to swat a fly: __USE_MALLOC

    +

    If you've already read this + advice and decided to define this macro, then the situation changes + thusly: +

      +
    1. __mem_interface, and +
    2. __alloc, and +
    3. __single_client_alloc are all typedef'd to + __malloc_alloc_template. +
    4. __default_alloc_template is no longer available. + At all. Anywhere. +
    +

    +

    Writing your own allocators

    +

    Depending on your application (a specific program, a generic library, + etc), allocator classes tend to be one of two styles: "SGI" + or "standard". See the comments in stl_alloc.h for more + information on this crucial difference. +

    +

    At the bottom of that header is a helper type, + _Alloc_traits, and various specializations of it. This + allows the container classes to make possible compile-time + optimizations based on features of the allocator. You should provide + a specialization of this type for your allocator (doing so takes only + two or three statements). +

    +

    Using non-default allocators

    +

    You can specify different memory management schemes on a per-container + basis, by overriding the default Allocator template + parameter. For example, an easy + (but nonportable) + method of specifying that only malloc/free should be used instead of + the default node allocator is: + 

    +    std::list <my_type, std::__malloc_alloc_template<0> >  my_malloc_based_list;
    + Likewise, a debugging form of whichever allocator is currently in use: + 
    +    std::deque <my_type, std::__debug_alloc<std::__alloc> >  debug_deque;
    +

    +

    inst

    +

    The __malloc_alloc_template and + __default_alloc_template classes take an integer parameter, + called inst here. This number is completely unused. +

    +

    More soon. +

    +

    +

    +

    3.0.x

    +

    I don't even remember. More soon. +

    +

    +

    +

    Return to top of page or to the FAQ. diff --git a/libstdc++-v3/docs/html/ext/sgiexts.html b/libstdc++-v3/docs/html/ext/sgiexts.html index 636f9f8b83b..674ffacc766 100644 --- a/libstdc++-v3/docs/html/ext/sgiexts.html +++ b/libstdc++-v3/docs/html/ext/sgiexts.html @@ -25,7 +25,7 @@ libstdc++-v3 for a description). Not every chapter may have extensions, and the extensions may come and go. Also, this page is incomplete because the author is pressed for time. Check back often; the latest change was on - $Date: 2001/10/11 18:41:47 $ (UTC). + $Date: 2001/11/23 16:29:01 $ (UTC).

    Descriptions range from the scanty to the verbose. You should also check @@ -60,6 +60,9 @@ libstdc++-v3

  • mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for backwards compatibility.

    +

    20.4.1 can use several different allocators; they are described on the + main extensions page. +

    20.4.3 is extended with a special version of get_temporary_buffer taking a second argument. The argument is a pointer, which is ignored, but can be used to specify the template -- 2.30.2