From patchwork Wed Jul 14 20:12:08 2010
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: [v3] update shared_ptr docs
From: Jonathan Wakely <jwakely.gcc@gmail.com>
X-Patchwork-Id: 58925
Message-Id: <AANLkTimkVOgDM9WKFBkgNRobokOi__O6Hy8cvjbJU3qn@mail.gmail.com>
To: "libstdc++" <libstdc++@gcc.gnu.org>, gcc-patches <gcc-patches@gcc.gnu.org>
Date: Wed, 14 Jul 2010 21:12:08 +0100

This updates the shared_ptr notes in the manual to reflect the current
state of the code

        * doc/xml/manual/shared_ptr.xml: Update.
        * doc/html/*: Regenerate.


Index: doc/xml/manual/shared_ptr.xml
===================================================================
--- doc/xml/manual/shared_ptr.xml	(revision 162174)
+++ doc/xml/manual/shared_ptr.xml	(working copy)
@@ -88,7 +88,7 @@ resource.
   <term><classname>_Sp_counted_base&lt;Lp&gt;</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
@@ -162,16 +162,6 @@ that simplifies the implementation sligh
     <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>
-
-    <para>
 C++0x-only features are: rvalue-ref/move support, allocator support,
 aliasing constructor, make_shared &amp; allocate_shared. Additionally,
 the constructors taking <classname>auto_ptr</classname> parameters are
@@ -306,18 +296,26 @@ used when libstdc++ is built without <li
     <title>Dual C++0x and TR1 Implementation</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.
+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>
 
@@ -421,18 +419,18 @@ the following types, depending on how th
     <title>Examples</title>
     <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>
     <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,11 +474,6 @@ the following types, depending on how th
       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>