diff options
Diffstat (limited to 'libstdc++-v3/doc/html/manual/memory.html')
| -rw-r--r-- | libstdc++-v3/doc/html/manual/memory.html | 84 |
1 files changed, 39 insertions, 45 deletions
diff --git a/libstdc++-v3/doc/html/manual/memory.html b/libstdc++-v3/doc/html/manual/memory.html index 90899d16a29..92e8b7f471e 100644 --- a/libstdc++-v3/doc/html/manual/memory.html +++ b/libstdc++-v3/doc/html/manual/memory.html @@ -93,7 +93,7 @@ or loading and unloading shared objects in memory. As such, using caching allocators on systems that do not support <code class="function">abi::__cxa_atexit</code> is not recommended. - </p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.impl"></a>Implementation</h4></div></div></div><div class="section" title="Interface Design"><div class="titlepage"><div><div><h5 class="title"><a id="id585444"></a>Interface Design</h5></div></div></div><p> + </p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.impl"></a>Implementation</h4></div></div></div><div class="section" title="Interface Design"><div class="titlepage"><div><div><h5 class="title"><a id="id377805"></a>Interface Design</h5></div></div></div><p> The only allocator interface that is supported is the standard C++ interface. As such, all STL containers have been adjusted, and all external allocators have @@ -106,7 +106,7 @@ </p><p> The base class that <code class="classname">allocator</code> is derived from may not be user-configurable. -</p></div><div class="section" title="Selecting Default Allocation Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id571671"></a>Selecting Default Allocation Policy</h5></div></div></div><p> +</p></div><div class="section" title="Selecting Default Allocation Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id406368"></a>Selecting Default Allocation Policy</h5></div></div></div><p> It's difficult to pick an allocation strategy that will provide maximum utility, without excessively penalizing some behavior. In fact, it's difficult just deciding which typical actions to measure @@ -143,7 +143,7 @@ The current default choice for <code class="classname">allocator</code> is <code class="classname">__gnu_cxx::new_allocator</code>. - </p></div><div class="section" title="Disabling Memory Caching"><div class="titlepage"><div><div><h5 class="title"><a id="id594539"></a>Disabling Memory Caching</h5></div></div></div><p> + </p></div><div class="section" title="Disabling Memory Caching"><div class="titlepage"><div><div><h5 class="title"><a id="id394979"></a>Disabling Memory Caching</h5></div></div></div><p> In use, <code class="classname">allocator</code> may allocate and deallocate using implementation-specified strategies and heuristics. Because of this, every call to an allocator object's @@ -308,11 +308,11 @@ A high-performance allocator that uses a bit-map to keep track of the used and unused memory locations. It has its own documentation, found <a class="link" href="bitmap_allocator.html" title="bitmap_allocator">here</a>. - </p></li></ol></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id577136"></a><p><span class="title"><i> + </p></li></ol></div></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="allocator.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry" title="ISO/IEC 14882:1998 Programming languages - C++"><a id="id399256"></a><p><span class="title"><i> ISO/IEC 14882:1998 Programming languages - C++ </i>. </span> isoc++_1998 - <span class="pagenums">20.4 Memory. </span></p></div><div class="biblioentry"><a id="id577150"></a><p><span class="biblioid"> + <span class="pagenums">20.4 Memory. </span></p></div><div class="biblioentry"><a id="id399271"></a><p><span class="biblioid"> <a class="ulink" href="http://www.drdobbs.com/cpp/184403759" target="_top"> <em class="citetitle"> The Standard Librarian: What Are Allocators Good For? @@ -320,19 +320,19 @@ </a> . </span><span class="author"><span class="firstname">Matt</span> <span class="surname">Austern</span>. </span><span class="publisher"><span class="publishername"> C/C++ Users Journal - . </span></span></p></div><div class="biblioentry"><a id="id621845"></a><p><span class="biblioid"> + . </span></span></p></div><div class="biblioentry"><a id="id405510"></a><p><span class="biblioid"> <a class="ulink" href="http://www.cs.umass.edu/~emery/hoard/" target="_top"> <em class="citetitle"> The Hoard Memory Allocator </em> </a> - . </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span></p></div><div class="biblioentry"><a id="id553878"></a><p><span class="biblioid"> + . </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span></p></div><div class="biblioentry"><a id="id451188"></a><p><span class="biblioid"> <a class="ulink" href="http://www.cs.umass.edu/~emery/pubs/berger-oopsla2002.pdf" target="_top"> <em class="citetitle"> Reconsidering Custom Memory Allocation </em> </a> - . </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="author"><span class="firstname">Ben</span> <span class="surname">Zorn</span>. </span><span class="author"><span class="firstname">Kathryn</span> <span class="surname">McKinley</span>. </span><span class="copyright">Copyright © 2002 OOPSLA. </span></p></div><div class="biblioentry"><a id="id576265"></a><p><span class="biblioid"> + . </span><span class="author"><span class="firstname">Emery</span> <span class="surname">Berger</span>. </span><span class="author"><span class="firstname">Ben</span> <span class="surname">Zorn</span>. </span><span class="author"><span class="firstname">Kathryn</span> <span class="surname">McKinley</span>. </span><span class="copyright">Copyright © 2002 OOPSLA. </span></p></div><div class="biblioentry"><a id="id387032"></a><p><span class="biblioid"> <a class="ulink" href="http://www.angelikalanger.com/Articles/C++Report/Allocators/Allocators.html" target="_top"> <em class="citetitle"> Allocator Types @@ -340,9 +340,9 @@ </a> . </span><span class="author"><span class="firstname">Klaus</span> <span class="surname">Kreft</span>. </span><span class="author"><span class="firstname">Angelika</span> <span class="surname">Langer</span>. </span><span class="publisher"><span class="publishername"> C/C++ Users Journal - . </span></span></p></div><div class="biblioentry" title="The C++ Programming Language"><a id="id564944"></a><p><span class="title"><i>The C++ Programming Language</i>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 . </span><span class="pagenums">19.4 Allocators. </span><span class="publisher"><span class="publishername"> + . </span></span></p></div><div class="biblioentry" title="The C++ Programming Language"><a id="id392077"></a><p><span class="title"><i>The C++ Programming Language</i>. </span><span class="author"><span class="firstname">Bjarne</span> <span class="surname">Stroustrup</span>. </span><span class="copyright">Copyright © 2000 . </span><span class="pagenums">19.4 Allocators. </span><span class="publisher"><span class="publishername"> Addison Wesley - . </span></span></p></div><div class="biblioentry" title="Yalloc: A Recycling C++ Allocator"><a id="id564390"></a><p><span class="title"><i>Yalloc: A Recycling C++ Allocator</i>. </span><span class="author"><span class="firstname">Felix</span> <span class="surname">Yen</span>. </span></p></div></div></div><div class="section" title="auto_ptr"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.auto_ptr"></a>auto_ptr</h3></div></div></div><div class="section" title="Limitations"><div class="titlepage"><div><div><h4 class="title"><a id="auto_ptr.limitations"></a>Limitations</h4></div></div></div><p>Explaining all of the fun and delicious things that can + . </span></span></p></div><div class="biblioentry" title="Yalloc: A Recycling C++ Allocator"><a id="id443714"></a><p><span class="title"><i>Yalloc: A Recycling C++ Allocator</i>. </span><span class="author"><span class="firstname">Felix</span> <span class="surname">Yen</span>. </span></p></div></div></div><div class="section" title="auto_ptr"><div class="titlepage"><div><div><h3 class="title"><a id="std.util.memory.auto_ptr"></a>auto_ptr</h3></div></div></div><div class="section" title="Limitations"><div class="titlepage"><div><div><h4 class="title"><a id="auto_ptr.limitations"></a>Limitations</h4></div></div></div><p>Explaining all of the fun and delicious things that can happen with misuse of the <code class="classname">auto_ptr</code> class template (called <acronym class="acronym">AP</acronym> here) would take some time. Suffice it to say that the use of <acronym class="acronym">AP</acronym> @@ -458,7 +458,7 @@ drops to zero. Derived classes override those functions to destroy resources in a context where the correct dynamic type is known. This is an application of the technique known as type erasure. - </p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.impl"></a>Implementation</h4></div></div></div><div class="section" title="Class Hierarchy"><div class="titlepage"><div><div><h5 class="title"><a id="id536213"></a>Class Hierarchy</h5></div></div></div><p> + </p></div><div class="section" title="Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.impl"></a>Implementation</h4></div></div></div><div class="section" title="Class Hierarchy"><div class="titlepage"><div><div><h5 class="title"><a id="id389991"></a>Class Hierarchy</h5></div></div></div><p> A <code class="classname">shared_ptr<T></code> contains a pointer of type <span class="type">T*</span> and an object of type <code class="classname">__shared_count</code>. The shared_count contains a @@ -466,7 +466,7 @@ pointer of type <span class="type">_Sp_counted_base*</span> which points to the object that maintains the reference-counts and destroys the managed resource. </p><div class="variablelist"><dl><dt><span class="term"><code class="classname">_Sp_counted_base<Lp></code></span></dt><dd><p> -The base of the hierarchy is parameterized on the lock policy alone. +The base of the hierarchy is parameterized on the lock policy (see below.) _Sp_counted_base doesn't depend on the type of pointer being managed, it only maintains the reference counts and calls virtual functions when the counts drop to zero. The managed object is destroyed when the last @@ -500,15 +500,7 @@ be forwarded to <span class="type">Tp</span>'s constructor. Unlike the other <code class="classname">_Sp_counted_*</code> classes, this one is parameterized on the type of object, not the type of pointer; this is purely a convenience that simplifies the implementation slightly. - </p></dd></dl></div></div><div class="section" title="Thread Safety"><div class="titlepage"><div><div><h5 class="title"><a id="id622537"></a>Thread Safety</h5></div></div></div><p> -The interface of <code class="classname">tr1::shared_ptr</code> was extended for C++0x -with support for rvalue-references and the other features from -N2351. As with other libstdc++ headers shared by TR1 and C++0x, -boost_shared_ptr.h uses conditional compilation, based on the macros -<code class="constant">_GLIBCXX_INCLUDE_AS_CXX0X</code> and -<code class="constant">_GLIBCXX_INCLUDE_AS_TR1</code>, to enable and disable -features. - </p><p> + </p></dd></dl></div></div><div class="section" title="Thread Safety"><div class="titlepage"><div><div><h5 class="title"><a id="id388735"></a>Thread Safety</h5></div></div></div><p> C++0x-only features are: rvalue-ref/move support, allocator support, aliasing constructor, make_shared & allocate_shared. Additionally, the constructors taking <code class="classname">auto_ptr</code> parameters are @@ -558,7 +550,7 @@ compiler, standard library, platform etc. For the version of shared_ptr in libstdc++ the compiler and library are fixed, which makes things much simpler: we have an atomic CAS or we don't, see Lock Policy below for details. -</p></div><div class="section" title="Selecting Lock Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id574548"></a>Selecting Lock Policy</h5></div></div></div><p> +</p></div><div class="section" title="Selecting Lock Policy"><div class="titlepage"><div><div><h5 class="title"><a id="id480578"></a>Selecting Lock Policy</h5></div></div></div><p> </p><p> There is a single <code class="classname">_Sp_counted_base</code> class, which is a template parameterized on the enum @@ -599,18 +591,24 @@ used when libstdc++ is built without <code class="literal">--enable-threads</cod <code class="filename">ext/atomicity.h</code>, which detect if the program is multi-threaded. If only one thread of execution exists in the program then less expensive non-atomic operations are used. - </p></div><div class="section" title="Dual C++0x and TR1 Implementation"><div class="titlepage"><div><div><h5 class="title"><a id="id552414"></a>Dual C++0x and TR1 Implementation</h5></div></div></div><p> + </p></div><div class="section" title="Dual C++0x and TR1 Implementation"><div class="titlepage"><div><div><h5 class="title"><a id="id399352"></a>Dual C++0x and TR1 Implementation</h5></div></div></div><p> +The interface of <code class="classname">tr1::shared_ptr</code> was extended for C++0x +with support for rvalue-references and the other features from N2351. +The <code class="classname">_Sp_counted_base</code> base class is implemented in +<code class="filename">tr1/boost_sp_shared_count.h</code> and is common to the TR1 +and C++0x versions of <code class="classname">shared_ptr</code>. +</p><p> The classes derived from <code class="classname">_Sp_counted_base</code> (see Class Hierarchy -below) and <code class="classname">__shared_count</code> are implemented separately for C++0x -and TR1, in <code class="filename">bits/boost_sp_shared_count.h</code> and -<code class="filename">tr1/boost_sp_shared_count.h</code> respectively. All other classes -including <code class="classname">_Sp_counted_base</code> are shared by both implementations. +above) and <code class="classname">__shared_count</code> are implemented separately for C++0x +and TR1, in <code class="filename">bits/shared_ptr.h</code> and +<code class="filename">tr1/shared_ptr.h</code> respectively. </p><p> The TR1 implementation is considered relatively stable, so is unlikely to change unless bug fixes require it. If the code that is common to both C++0x and TR1 modes needs to diverge further then it might be necessary to -duplicate additional classes and only make changes to the C++0x versions. -</p></div><div class="section" title="Related functions and classes"><div class="titlepage"><div><div><h5 class="title"><a id="id530167"></a>Related functions and classes</h5></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="code">dynamic_pointer_cast</code>, <code class="code">static_pointer_cast</code>, +duplicate <code class="classname">_Sp_counted_base</code> and only make changes to +the C++0x version. +</p></div><div class="section" title="Related functions and classes"><div class="titlepage"><div><div><h5 class="title"><a id="id404250"></a>Related functions and classes</h5></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="code">dynamic_pointer_cast</code>, <code class="code">static_pointer_cast</code>, <code class="code">const_pointer_cast</code></span></dt><dd><p> As noted in N2351, these functions can be implemented non-intrusively using the alias constructor. However the aliasing constructor is only available @@ -643,15 +641,15 @@ is called. Users should not try to use this. As well as the extra constructors, this implementation also needs some members of _Sp_counted_deleter to be protected where they could otherwise be private. - </p></dd></dl></div></div></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.using"></a>Use</h4></div></div></div><div class="section" title="Examples"><div class="titlepage"><div><div><h5 class="title"><a id="id558154"></a>Examples</h5></div></div></div><p> + </p></dd></dl></div></div></div><div class="section" title="Use"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.using"></a>Use</h4></div></div></div><div class="section" title="Examples"><div class="titlepage"><div><div><h5 class="title"><a id="id478086"></a>Examples</h5></div></div></div><p> Examples of use can be found in the testsuite, under - <code class="filename">testsuite/tr1/2_general_utilities/shared_ptr</code>. - </p></div><div class="section" title="Unresolved Issues"><div class="titlepage"><div><div><h5 class="title"><a id="id558170"></a>Unresolved Issues</h5></div></div></div><p> - The resolution to C++ Standard Library issue <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#674" target="_top">674</a>, - "shared_ptr interface changes for consistency with N1856" will - need to be implemented after it is accepted into the working - paper. Issue <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#743" target="_top">743</a> - might also require changes. + <code class="filename">testsuite/tr1/2_general_utilities/shared_ptr</code>, + <code class="filename">testsuite/20_util/shared_ptr</code> + and + <code class="filename">testsuite/20_util/weak_ptr</code>. + </p></div><div class="section" title="Unresolved Issues"><div class="titlepage"><div><div><h5 class="title"><a id="id397929"></a>Unresolved Issues</h5></div></div></div><p> + The <span class="emphasis"><em><code class="classname">shared_ptr</code> atomic access</em></span> + clause in the C++0x working draft is not implemented in GCC. </p><p> The <span class="type">_S_single</span> policy uses atomics when used in MT code, because it uses the same dispatcher functions that check @@ -685,16 +683,12 @@ be private. </p><p> tr1::_Sp_deleter could be a private member of tr1::__shared_count but it would alter the ABI. - </p><p> - Exposing the alias constructor in TR1 mode could simplify the - *_pointer_cast functions. Constructor could be private in TR1 - mode, with the cast functions as friends. </p></div></div><div class="section" title="Acknowledgments"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.ack"></a>Acknowledgments</h4></div></div></div><p> The original authors of the Boost shared_ptr, which is really nice code to work with, Peter Dimov in particular for his help and invaluable advice on thread safety. Phillip Jordan and Paolo Carlini for the lock policy implementation. - </p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id569700"></a><p><span class="biblioid"> + </p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h4 class="title"><a id="shared_ptr.biblio"></a>Bibliography</h4></div></div></div><div class="biblioentry"><a id="id444231"></a><p><span class="biblioid"> <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm" target="_top"> <em class="citetitle"> Improving shared_ptr for C++0x, Revision 2 @@ -702,7 +696,7 @@ be private. </a> . </span><span class="subtitle"> N2351 - . </span></p></div><div class="biblioentry"><a id="id552965"></a><p><span class="biblioid"> + . </span></p></div><div class="biblioentry"><a id="id444254"></a><p><span class="biblioid"> <a class="ulink" href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html" target="_top"> <em class="citetitle"> C++ Standard Library Active Issues List @@ -710,7 +704,7 @@ be private. </a> . </span><span class="subtitle"> N2456 - . </span></p></div><div class="biblioentry"><a id="id552988"></a><p><span class="biblioid"> + . </span></p></div><div class="biblioentry"><a id="id400755"></a><p><span class="biblioid"> <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf" target="_top"> <em class="citetitle"> Working Draft, Standard for Programming Language C++ @@ -718,7 +712,7 @@ be private. </a> . </span><span class="subtitle"> N2461 - . </span></p></div><div class="biblioentry"><a id="id554228"></a><p><span class="biblioid"> + . </span></p></div><div class="biblioentry"><a id="id424141"></a><p><span class="biblioid"> <a class="ulink" href="http://boost.org/libs/smart_ptr/shared_ptr.htm" target="_top">shared_ptr <em class="citetitle"> Boost C++ Libraries documentation, shared_ptr |