diff options
Diffstat (limited to 'libstdc++-v3/doc/xml/manual/shared_ptr.xml')
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/shared_ptr.xml | 156 |
1 files changed, 71 insertions, 85 deletions
diff --git a/libstdc++-v3/doc/xml/manual/shared_ptr.xml b/libstdc++-v3/doc/xml/manual/shared_ptr.xml index 70e000dcc5b..4ef5f72b6a6 100644 --- a/libstdc++-v3/doc/xml/manual/shared_ptr.xml +++ b/libstdc++-v3/doc/xml/manual/shared_ptr.xml @@ -1,7 +1,8 @@ -<section id="std.util.memory.shared_ptr" xreflabel="shared_ptr"> +<section xmlns="http://docbook.org/ns/docbook" version="5.0" + xml:id="std.util.memory.shared_ptr" xreflabel="shared_ptr"> <?dbhtml filename="shared_ptr.html"?> -<sectioninfo> +<info><title>shared_ptr</title> <keywordset> <keyword> ISO C++ @@ -10,17 +11,17 @@ shared_ptr </keyword> </keywordset> -</sectioninfo> +</info> + -<title>shared_ptr</title> <para> The shared_ptr class template stores a pointer, usually obtained via new, and implements shared ownership semantics. </para> -<section id="shared_ptr.req"> -<title>Requirements</title> +<section xml:id="shared_ptr.req"><info><title>Requirements</title></info> + <para> </para> @@ -43,8 +44,8 @@ and implements shared ownership semantics. </para> </section> -<section id="shared_ptr.design_issues"> -<title>Design Issues</title> +<section xml:id="shared_ptr.design_issues"><info><title>Design Issues</title></info> + <para> @@ -67,11 +68,11 @@ technique known as type erasure. </section> -<section id="shared_ptr.impl"> -<title>Implementation</title> +<section xml:id="shared_ptr.impl"><info><title>Implementation</title></info> - <section> - <title>Class Hierarchy</title> + + <section><info><title>Class Hierarchy</title></info> + <para> A <classname>shared_ptr<T></classname> contains a pointer of @@ -88,7 +89,7 @@ resource. <term><classname>_Sp_counted_base<Lp></classname></term> <listitem> <para> -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 @@ -158,18 +159,8 @@ that simplifies the implementation slightly. </section> - <section> - <title>Thread Safety</title> - - <para> -The interface of <classname>tr1::shared_ptr</classname> 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 -<constant>_GLIBCXX_INCLUDE_AS_CXX0X</constant> and -<constant>_GLIBCXX_INCLUDE_AS_TR1</constant>, to enable and disable -features. - </para> + <section><info><title>Thread Safety</title></info> + <para> C++0x-only features are: rvalue-ref/move support, allocator support, @@ -180,8 +171,8 @@ deprecated in C++0x mode. <para> The -<ulink url="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread -Safety</ulink> section of the Boost shared_ptr documentation says "shared_ptr +<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread +Safety</link> section of the Boost shared_ptr documentation says "shared_ptr objects offer the same level of thread safety as built-in types." The implementation must ensure that concurrent updates to separate shared_ptr instances are correct even when those instances share a reference count e.g. @@ -234,8 +225,8 @@ Policy below for details. </section> - <section> - <title>Selecting Lock Policy</title> + <section><info><title>Selecting Lock Policy</title></info> + <para> </para> @@ -264,8 +255,8 @@ available policies are: </para> <para> Selected when GCC supports a builtin atomic compare-and-swap operation -on the target processor (see <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Atomic -Builtins</ulink>.) The reference counts are maintained using a lock-free +on the target processor (see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Atomic +Builtins</link>.) The reference counts are maintained using a lock-free algorithm and GCC's atomic builtins, which provide the required memory synchronisation. </para> @@ -302,27 +293,35 @@ used when libstdc++ is built without <literal>--enable-threads</literal>. </para> </section> - <section> - <title>Dual C++0x and TR1 Implementation</title> + <section><info><title>Dual C++0x and TR1 Implementation</title></info> + + +<para> +The interface of <classname>tr1::shared_ptr</classname> was extended for C++0x +with support for rvalue-references and the other features from N2351. +The <classname>_Sp_counted_base</classname> base class is implemented in +<filename>tr1/boost_sp_shared_count.h</filename> and is common to the TR1 +and C++0x versions of <classname>shared_ptr</classname>. +</para> <para> The classes derived from <classname>_Sp_counted_base</classname> (see Class Hierarchy -below) and <classname>__shared_count</classname> are implemented separately for C++0x -and TR1, in <filename>bits/boost_sp_shared_count.h</filename> and -<filename>tr1/boost_sp_shared_count.h</filename> respectively. All other classes -including <classname>_Sp_counted_base</classname> are shared by both implementations. +above) and <classname>__shared_count</classname> are implemented separately for C++0x +and TR1, in <filename>bits/shared_ptr.h</filename> and +<filename>tr1/shared_ptr.h</filename> respectively. </para> <para> 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. +duplicate <classname>_Sp_counted_base</classname> and only make changes to +the C++0x version. </para> </section> -<section> -<title>Related functions and classes</title> +<section><info><title>Related functions and classes</title></info> + <variablelist> @@ -414,25 +413,25 @@ the following types, depending on how the shared_ptr is constructed. </listitem> --> -<section id="shared_ptr.using"> -<title>Use</title> +<section xml:id="shared_ptr.using"><info><title>Use</title></info> + - <section> - <title>Examples</title> + <section><info><title>Examples</title></info> + <para> Examples of use can be found in the testsuite, under - <filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>. + <filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>, + <filename class="directory">testsuite/20_util/shared_ptr</filename> + and + <filename class="directory">testsuite/20_util/weak_ptr</filename>. </para> </section> - <section> - <title>Unresolved Issues</title> + <section><info><title>Unresolved Issues</title></info> + <para> - The resolution to C++ Standard Library issue <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#674">674</ulink>, - "shared_ptr interface changes for consistency with N1856" will - need to be implemented after it is accepted into the working - paper. Issue <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#743">743</ulink> - might also require changes. + The <emphasis><classname>shared_ptr</classname> atomic access</emphasis> + clause in the C++0x working draft is not implemented in GCC. </para> <para> @@ -476,17 +475,12 @@ the following types, depending on how the shared_ptr is constructed. would alter the ABI. </para> - <para> - 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. - </para> </section> </section> -<section id="shared_ptr.ack"> -<title>Acknowledgments</title> +<section xml:id="shared_ptr.ack"><info><title>Acknowledgments</title></info> + <para> The original authors of the Boost shared_ptr, which is really nice @@ -497,56 +491,48 @@ the following types, depending on how the shared_ptr is constructed. </section> -<bibliography id="shared_ptr.biblio"> -<title>Bibliography</title> +<bibliography xml:id="shared_ptr.biblio"><info><title>Bibliography</title></info> + <biblioentry> - <biblioid class="uri"> - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm"> - <citetitle> - Improving shared_ptr for C++0x, Revision 2 - </citetitle> - </ulink> + <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm" class="uri"> </biblioid> + <citetitle> + Improving shared_ptr for C++0x, Revision 2 + </citetitle> <subtitle> N2351 </subtitle> </biblioentry> <biblioentry> - <biblioid class="uri"> - <ulink url="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html"> - <citetitle> - C++ Standard Library Active Issues List - </citetitle> - </ulink> + <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html" class="uri"> </biblioid> + <citetitle> + C++ Standard Library Active Issues List + </citetitle> <subtitle> N2456 </subtitle> </biblioentry> <biblioentry> - <biblioid class="uri"> - <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf"> - <citetitle> - Working Draft, Standard for Programming Language C++ - </citetitle> - </ulink> + <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf" class="uri"> </biblioid> + <citetitle> + Working Draft, Standard for Programming Language C++ + </citetitle> <subtitle> N2461 </subtitle> </biblioentry> <biblioentry> - <biblioid class="uri"> - <ulink url="http://boost.org/libs/smart_ptr/shared_ptr.htm">shared_ptr - <citetitle> - Boost C++ Libraries documentation, shared_ptr - </citetitle> - </ulink> + <biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://boost.org/libs/smart_ptr/shared_ptr.htm" class="uri">shared_ptr </biblioid> + <citetitle> + Boost C++ Libraries documentation, shared_ptr + </citetitle> <subtitle> N2461 </subtitle> |