From 86e9a322bae9a9635666fbe20ef4b116cae69207 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Wed, 5 Feb 2003 12:56:48 +0000 Subject: [PATCH] Documentation fixes, make_shared -> get_shared_ptr. [SVN r17230] --- enable_shared_from_this.html | 12 +++---- include/boost/weak_ptr.hpp | 14 +++++--- index.htm | 8 +++-- intrusive_ptr.html | 14 ++++---- shared_ptr.htm | 59 +++++++++++++++++++++------------- sp_techniques.html | 2 +- test/shared_ptr_basic_test.cpp | 10 +++--- test/shared_ptr_test.cpp | 2 +- test/weak_ptr_test.cpp | 6 ++-- weak_ptr.htm | 32 ++++++------------ 10 files changed, 85 insertions(+), 74 deletions(-) diff --git a/enable_shared_from_this.html b/enable_shared_from_this.html index 425a781..8ff0a73 100644 --- a/enable_shared_from_this.html +++ b/enable_shared_from_this.html @@ -71,9 +71,9 @@ public:

Requires: enable_shared_from_this<T> must be an accessible base class of T. *this must be a subobject - of an instance t of type T. There must have - existed at least one shared_ptr instance p pointing - to t. + of an instance t of type T . There must exist + at least one shared_ptr instance p that owns + t.

Returns: A shared_ptr<T> instance r that shares @@ -85,9 +85,9 @@ public:


- Copyright © 2002 by Peter Dimov. Permission to copy, use, modify, sell and - distribute this document is granted provided this copyright notice appears in - all copies. This document is provided "as is" without express or implied + Copyright © 2002, 2003 by Peter Dimov. Permission to copy, use, modify, sell + and distribute this document is granted provided this copyright notice appears + in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

diff --git a/include/boost/weak_ptr.hpp b/include/boost/weak_ptr.hpp index 9d56858..29e7e9f 100644 --- a/include/boost/weak_ptr.hpp +++ b/include/boost/weak_ptr.hpp @@ -24,7 +24,7 @@ namespace boost { -template shared_ptr make_shared(weak_ptr const & r); // never throws +template shared_ptr get_shared_ptr(weak_ptr const & r); // never throws template class weak_ptr { @@ -64,7 +64,7 @@ public: template weak_ptr(weak_ptr const & r): pn(r.pn) // never throws { - px = boost::make_shared(r).get(); + px = boost::get_shared_ptr(r).get(); } template @@ -77,7 +77,7 @@ public: template weak_ptr & operator=(weak_ptr const & r) // never throws { - px = boost::make_shared(r).get(); + px = boost::get_shared_ptr(r).get(); pn = r.pn; return *this; } @@ -151,7 +151,7 @@ template void swap(weak_ptr & a, weak_ptr & b) a.swap(b); } -template shared_ptr make_shared(weak_ptr const & r) // never throws +template shared_ptr get_shared_ptr(weak_ptr const & r) // never throws { #if defined(BOOST_HAS_THREADS) @@ -180,6 +180,12 @@ template shared_ptr make_shared(weak_ptr const & r) // never thro #endif } +// deprecated, provided for backward compatibility +template shared_ptr make_shared(weak_ptr const & r) +{ + return boost::get_shared_ptr(r); +} + } // namespace boost #ifdef BOOST_MSVC diff --git a/index.htm b/index.htm index f53a933..2c775ac 100644 --- a/index.htm +++ b/index.htm @@ -33,6 +33,10 @@ Header shared_array.hpp.
  • Header weak_ptr.hpp.
    • +
  • + Header enable_shared_from_this.hpp.
    • +
  • + Header intrusive_ptr.hpp.
  • Test program smart_ptr_test.cpp.
  • @@ -41,7 +45,7 @@ by Peter Dimov and Darin Adler.
    • -

    Revised - 1 February 2002 .

    +
    +

    $Date$

    diff --git a/intrusive_ptr.html b/intrusive_ptr.html index fca484d..22bbc0c 100644 --- a/intrusive_ptr.html +++ b/intrusive_ptr.html @@ -19,9 +19,9 @@ the reference count by using an unqualified call to the function intrusive_ptr_add_ref, passing it the pointer as an argument. Similarly, when an intrusive_ptr is destroyed, it calls intrusive_ptr_release; this function is - responsible for destroying the object when its reference count drops to - zero. The user is expected to provide suitable definitions of these two - functions. On compilers that support argument-dependent lookup, intrusive_ptr_add_ref + responsible for destroying the object when its reference count drops to zero. + The user is expected to provide suitable definitions of these two functions. On + compilers that support argument-dependent lookup, intrusive_ptr_add_ref and intrusive_ptr_release should be defined in the namespace that corresponds to their parameter; otherwise, the definitions need to go in namespace boost.

    @@ -39,8 +39,8 @@
  • intrusive_ptr<T> can be constructed from an arbitrary raw pointer of type T *.
    • -

    As a general rule, if it isn't obvious whether intrusive_ptr - better fits your needs than shared_ptr, try a shared_ptr-based +

    As a general rule, if it isn't obvious whether intrusive_ptr better + fits your needs than shared_ptr, try a shared_ptr-based design first.

    Synopsis

    namespace boost {
@@ -268,9 +268,9 @@ intrusive_ptr & operator=(T * r);

    $Date$

    - Copyright © 2003 Peter Dimov. Permission to copy, use, modify, sell and + Copyright © 2003 Peter Dimov. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied - warranty, and with no claim as to its suitability for any purpose.

    + warranty, and with no claim as to its suitability for any purpose.

    diff --git a/shared_ptr.htm b/shared_ptr.htm index 652cc49..bdd8d22 100644 --- a/shared_ptr.htm +++ b/shared_ptr.htm @@ -8,7 +8,6 @@

    c++boost.gif (8819 bytes)shared_ptr class template

    Introduction
    - Motivation
    Best Practices
    Synopsis
    Members
    @@ -47,8 +46,6 @@ to shared_ptr<T const>, to shared_ptr<U> where U is an accessible base of T, and to shared_ptr<void>.

    -

    Motivation

    -

    [...]

    Best Practices

    A simple guideline that nearly eliminates the possibility of memory leaks is: always use a named smart pointer variable to hold the result of new. @@ -83,8 +80,8 @@ void bad() evaluated in unspecified order, it is possible for new int(2) to be evaluated first, g() second, and we may never get to the shared_ptr constructor if g throws an exception. - See Herb Sutter's treatment of - the issue for more information.

    + See Herb Sutter's treatment (also + here) of the issue for more information.

    Synopsis

    namespace boost {
 
@@ -150,6 +147,8 @@ void bad()
   template<class E, class T, class Y>
     std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, shared_ptr<Y> const & p);
 
+  template<class D, class T>
+    D * get_deleter(shared_ptr<T> const & p);
 }

    [It might be convenient to relax the requirements on shared_ptr's signature, allowing an additional, defaulted, template parameter; the parameter @@ -193,7 +192,7 @@ void bad() must be a complete type. The expression delete p must be well-formed, must not invoke undefined behavior, and must not throw exceptions.

    -

    Effects: Constructs a shared_ptr, storing a copy of p.

    +

    Effects: Constructs a shared_ptr that owns the pointer p.

    Postconditions: use_count() == 1 && get() == p.

    Throws: std::bad_alloc or an implementation-defined exception when a resource other than memory could not be obtained.

    @@ -220,7 +219,8 @@ void bad() of D must not throw. The expression d(p) must be well-formed, must not invoke undefined behavior, and must not throw exceptions.

    -

    Effects: Constructs a shared_ptr, storing a copy of p and d.

    +

    Effects: Constructs a shared_ptr that owns the pointer + p and the deleter d.

    Postconditions: use_count() == 1 && get() == p.

    Throws: std::bad_alloc or an implementation-defined exception when a resource other than memory could not be obtained.

    @@ -288,9 +288,19 @@ template<class Y> shared_ptr(shared_ptr<Y> const & r); // never

    destructor

    ~shared_ptr(); // never throws
    -

    Effects: If *this is the sole owner (use_count() == 1), - destroys the object pointed to by the stored pointer as specified at - construction time.

    +

    Effects:

    +
      +
    • + If *this is empty, or shares ownership with + another shared_ptr instance (use_count() > 1), + there are no side effects. +
    • + Otherwise, if *this owns a pointer p + and a deleter d, d(p) + is called. +
    • + Otherwise, *this owns a pointer p, + and delete p is called.

    Throws: nothing.

    assignment

    @@ -381,7 +391,7 @@ q = p;

    [The conversion to bool is not merely syntactic sugar. It allows shared_ptrs to be declared in conditions when using dynamic_pointer_cast or - make_shared.]

    + get_shared_ptr.]

    swap

    void swap(shared_ptr & b); // never throws
    @@ -489,6 +499,14 @@ q = p;

    Effects: os << p.get();.

    Returns: os.

    +

    get_deleter

    + 
    template<class D, class T>
+    D * get_deleter(shared_ptr<T> const & p);
    +
    +

    Returns: If *this owns a deleter d + of type (cv-unqualified) D, returns &d; + otherwise returns 0.

    +

    Example

    See shared_ptr_example.cpp for a complete example program. The program builds a std::vector and std::set @@ -505,7 +523,7 @@ q = p;

    One common usage of shared_ptr is to implement a handle/body (also called pimpl) idiom which avoids exposing the body (implementation) in the header file.

    -

    The shared_ptr_example2_test.cpp +

    The shared_ptr_example2_test.cpp sample program includes a header file, shared_ptr_example2.hpp, which uses a shared_ptr<> to an incomplete type to hide the implementation. The instantiation of member functions which require a complete @@ -648,20 +666,15 @@ int * p = a.release(); obtain a non-const pointer from a const one and then proceed to modify the object through it.shared_ptr is "as close to raw pointers as possible but no closer".
    -

    -

    Q. Why doesn't shared_ptr provide (your pet feature here)?

    -

    - A. Because (your pet feature here) would mandate a reference counted - implementation or a linked list implementation, or some other specific - implementation. This is not the intent.
    +

    $Date$

    -

    Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. - Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and - distribute this document is granted provided this copyright notice appears in - all copies. This document is provided "as is" without express or implied - warranty, and with no claim as to its suitability for any purpose.

    +

    Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. + Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and + distribute this document is granted provided this copyright notice appears in + all copies. This document is provided "as is" without express or implied + warranty, and with no claim as to its suitability for any purpose.

    diff --git a/sp_techniques.html b/sp_techniques.html index cc214b8..aa104ab 100644 --- a/sp_techniques.html +++ b/sp_techniques.html @@ -413,7 +413,7 @@ public: virtual shared_ptr<X> getX() { - shared_ptr<X> px = make_shared(weak_this); + shared_ptr<X> px = get_shared_ptr(weak_this); return px; } }; diff --git a/test/shared_ptr_basic_test.cpp b/test/shared_ptr_basic_test.cpp index 151af07..db5c0c1 100644 --- a/test/shared_ptr_basic_test.cpp +++ b/test/shared_ptr_basic_test.cpp @@ -94,7 +94,7 @@ template void test_is_Y(boost::shared_ptr const & p) template void test_is_Y(boost::weak_ptr const & p) { - boost::shared_ptr q = boost::make_shared(p); + boost::shared_ptr q = boost::get_shared_ptr(p); BOOST_TEST(q.get() != 0); BOOST_TEST(q->id() == 2); } @@ -221,7 +221,7 @@ int main() { } - test_is_zero(boost::make_shared(wp1)); + test_is_zero(boost::get_shared_ptr(wp1)); weak_ptr wp2 = static_pointer_cast(p5); @@ -232,10 +232,10 @@ int main() // Scoped to not affect the subsequent use_count() tests. { shared_ptr sp2(wp2); - test_is_nonzero(boost::make_shared(wp2)); + test_is_nonzero(boost::get_shared_ptr(wp2)); } - weak_ptr wp3 = dynamic_pointer_cast(boost::make_shared(wp2)); + weak_ptr wp3 = dynamic_pointer_cast(boost::get_shared_ptr(wp2)); BOOST_TEST(wp3.use_count() == 1); test_shared(wp2, wp3); @@ -246,7 +246,7 @@ int main() test_shared(wp2, wp4); wp1 = p2; - test_is_zero(boost::make_shared(wp1)); + test_is_zero(boost::get_shared_ptr(wp1)); wp1 = p4; wp1 = wp3; diff --git a/test/shared_ptr_test.cpp b/test/shared_ptr_test.cpp index 4e3e80b..7525d7a 100644 --- a/test/shared_ptr_test.cpp +++ b/test/shared_ptr_test.cpp @@ -3094,7 +3094,7 @@ public: virtual boost::shared_ptr getX() { - boost::shared_ptr px = boost::make_shared(weak_this); + boost::shared_ptr px = boost::get_shared_ptr(weak_this); return px; } }; diff --git a/test/weak_ptr_test.cpp b/test/weak_ptr_test.cpp index 8f76d61..7408bb9 100644 --- a/test/weak_ptr_test.cpp +++ b/test/weak_ptr_test.cpp @@ -1183,14 +1183,14 @@ void test() } // namespace n_comparison -namespace n_make_shared +namespace n_get_shared_ptr { void test() { } -} // namespace n_make_shared +} // namespace n_get_shared_ptr namespace n_map { @@ -1272,7 +1272,7 @@ int main() n_use_count::test(); n_swap::test(); n_comparison::test(); - n_make_shared::test(); + n_get_shared_ptr::test(); n_map::test(); diff --git a/weak_ptr.htm b/weak_ptr.htm index 2bf395b..80fcb7a 100644 --- a/weak_ptr.htm +++ b/weak_ptr.htm @@ -8,7 +8,6 @@

    c++boost.gif (8819 bytes)weak_ptr class template

    Introduction
    - Motivation
    Synopsis
    Members
    Free Functions
    @@ -18,12 +17,12 @@

    The weak_ptr class template stores a "weak reference" to an object that's already managed by a shared_ptr. To access the object, a weak_ptr can be converted to a shared_ptr using - the shared_ptr constructor or the function - make_shared. When the last shared_ptr to the object - goes away and the object is deleted, the attempt to obtain a shared_ptr + the shared_ptr constructor or the function + get_shared_ptr. When the last shared_ptr to the + object goes away and the object is deleted, the attempt to obtain a shared_ptr from the weak_ptr instances that refer to the deleted object will fail: the constructor will throw an exception of type boost::bad_weak_ptr, - and make_shared will return an empty shared_ptr.

    + and get_shared_ptr will return an empty shared_ptr.

    Every weak_ptr meets the CopyConstructible and Assignable requirements of the C++ Standard Library, and so can be used in standard library containers. Comparison operators are supplied so that weak_ptr works with the @@ -56,7 +55,7 @@ weak_ptr<int> q(p); // some time later -if(shared_ptr<int> r = make_shared(q)) +if(shared_ptr<int> r = get_shared_ptr(q)) { // use *r } @@ -64,17 +63,6 @@ if(shared_ptr<int> r = make_shared(q))

    Now r holds a reference to the object that was pointed by q. Even if p.reset() is executed in another thread, the object will stay alive until r goes out of scope (or is reset.)

    -

    Motivation

    -

    [a mechanism to avoid dangling pointers]

    -

    [a way to break shared_ptr cycles]

    -

    [weak pointer to this - a technique to obtain a shared_ptr to this from within a - member function]

    -

    [map<weak_ptr, ...> - a technique to associate arbitrary data with - shared_ptr managed objects]

    -

    [gameobject/tank example]

    -

    [cache example]

    -

    [comparison: weak_ptr vs observer and other approaches]

    -

    [hard to reinvent, subtle implementation, with many pitfalls]

    Synopsis

    namespace boost {
 
@@ -110,7 +98,7 @@ if(shared_ptr<int> r = make_shared(q))
     void swap(weak_ptr<T> & a, weak_ptr<T> & b);
 
   template<class T>
-    shared_ptr<T> make_shared(weak_ptr<T> const & r);
+    shared_ptr<T> get_shared_ptr(weak_ptr<T> const & r);
 
 }
    @@ -210,9 +198,9 @@ template<class Y> weak_ptr & operator=(shar

    Notes: Matches the interface of std::swap. Provided as an aid to generic programming.

    -

    make_shared

    +

    get_shared_ptr

    template<class T>
-  shared_ptr<T> make_shared(weak_ptr<T> & const r)
    + shared_ptr<T> get_shared_ptr(weak_ptr<T> & const r)

    Returns: r.expired()? shared_ptr<T>(): shared_ptr<T>(r).

    Throws: nothing.

    @@ -249,11 +237,11 @@ public:

    $Date$

    -

    Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. +

    Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied - warranty, and with no claim as to its suitability for any purpose.

    + warranty, and with no claim as to its suitability for any purpose.