From 675d09723a21c438c7d79ed309d0c738cc8116e4 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Sun, 12 Jun 2005 12:58:17 +0000 Subject: [PATCH] Lock-free implementation documented, minor changes to align with TR1 [SVN r29536] --- shared_ptr.htm | 98 ++++++++++++++++++++++++-------------------------- weak_ptr.htm | 8 ++--- 2 files changed, 51 insertions(+), 55 deletions(-) diff --git a/shared_ptr.htm b/shared_ptr.htm index 3422166..0b83d1f 100644 --- a/shared_ptr.htm +++ b/shared_ptr.htm @@ -20,7 +20,7 @@ Programming Techniques

Introduction

The shared_ptr class template stores a pointer to a dynamically allocated - object, typically with a C++ new-expression . The object pointed to is + object, typically with a C++ new-expression. The object pointed to is guaranteed to be deleted when the last shared_ptr pointing to it is destroyed or reset. See the example.

Every shared_ptr meets the CopyConstructible and Assignable @@ -47,6 +47,13 @@ to shared_ptr<T const>, to shared_ptr<U> where U is an accessible base of T, and to shared_ptr<void>.

+

shared_ptr is now part of TR1, the first C++ + Library Technical Report. The latest draft of TR1 is available + at the following location:

+

http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2005/n1745.pdf (1.36Mb + PDF)

+

This implementation conforms to the TR1 specification, with the only exception + that it resides in namespace boost instead of std::tr1.

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. @@ -154,15 +161,6 @@ void bad() 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 - can encode the threading model, for example. This would help in detecting - possible ODR violations.

-

On the other hand, using shared_ptr as an argument to a - template template parameter requires an exact signature match. Metaprogramming - experts tend to deemphasize template template parameters as they are too - inflexible, but the alternative is typically an std::allocator::rebind-type - "hack".]

Members

element_type

typedef T element_type;
@@ -174,22 +172,12 @@ void bad()

Effects: Constructs an empty shared_ptr. Empty shared_ptr objects have an unspecified use_count.

-

Postconditions: get() == 0.

+

Postconditions: use_count() == 0 && get() == 0.

Throws: nothing.

[The nothrow guarantee is important, since reset() is specified in terms of the default constructor; this implies that the constructor must not - allocate memory.

-

There are two possible implementations, one stores 0 as a pointer to the - reference count, the other uses a single statically allocated count for all - default-constructed shared_ptrs. The second option is - difficult to achieve in the current header-only reference implementation due to - thread safety issues and initialization order, but it should not be precluded - by the specification. That's why the use_count() has been left unspecified.

-

A future release may enable shared_ptr construction from a - literal zero, for consistency with built-in pointers. It is not clear yet - whether this constructor should be left implicit, enabling 0 to - be used as a shorthand for shared_ptr<T>().]

+ allocate memory.]

template<class Y> explicit shared_ptr(Y * p);

Requirements: p must be convertible to T *. Y @@ -198,8 +186,8 @@ void bad()

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.

+

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

Exception safety: If an exception is thrown, delete p is called.

Notes: p must be a pointer to an object that was @@ -226,8 +214,8 @@ void bad()

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.

+

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

Exception safety: If an exception is thrown, d(p) is called.

Notes: When the the time comes to delete the object pointed to by p, the stored copy of d is invoked with the stored copy of p @@ -245,17 +233,10 @@ void bad()

The requirement that the copy constructor of D does not throw comes from the pass by value. If the copy constructor throws, the pointer is leaked. Removing the requirement requires a pass by (const) reference.

-

Pass by reference is problematic since (1) pass by value conveniently changes - functions (function references) to function pointers (this has to be performed - manually otherwise and some compilers may not be able to do it) and (2) const - references don't currently (per the standard) bind to functions. This can be - solved (I think) but it requires an overload set that breaks on many compilers - due to 14.5.5.2 problems (and of course it will break on compilers that don't - do partial ordering at all.)

-

The main problem with pass by reference, though, lies in its interaction with - rvalues. A const reference may still cause a copy, and will require a const - operator(). A non-const reference won't bind to an rvalue at all. A good - solution to this problem is the rvalue reference proposed in +

The main problem with pass by reference lies in its interaction with rvalues. A + const reference may still cause a copy, and will require a const operator(). A + non-const reference won't bind to an rvalue at all. A good solution to this + problem is the rvalue reference proposed in N1377/N1385.]

shared_ptr(shared_ptr const & r); // never throws
 template<class Y> shared_ptr(shared_ptr<Y> const & r); // never throws
@@ -280,8 +261,8 @@ template<class Y> shared_ptr(shared_ptr<Y> const & r); // never

Effects: Constructs a shared_ptr, as if by storing a copy of r.release().

Postconditions: use_count() == 1.

-

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

+

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

Exception safety: If an exception is thrown, the constructor has no effect.

@@ -325,12 +306,6 @@ q = p;

both assignments may be no-ops.

-

[Some experts consider the note to be redundant, as it appears to essentially - mirror the "as if" rule. However, experience suggests that when C++ code is - used to describe effects, it is often misinterpreted as required - implementation. In addition, it is not entirely clear whether the "as if" rule - actually applies here, so it's better to be explicit about the possible - optimizations.]

reset

void reset(); // never throws
@@ -602,11 +577,32 @@ p3.reset(new int(1)); // thread B p3.reset(new int(2)); // undefined, multiple writes -

shared_ptr uses Boost.Config - to detect whether the implementation supports threads. If your program is - single-threaded, but your platform is autodetected by Boost.Config - as supporting multiple threads, #define BOOST_DISABLE_THREADS to - eliminate the thread safety overhead.

+

 

+

Starting with Boost release 1.33.0, shared_ptr uses a lock-free + implementation on the following platforms:

+
    +
  • + GNU GCC on x86 or x86-64;
    • +
  • + GNU GCC on IA64;
    • +
  • + Metrowerks CodeWarrior on PowerPC;
    • +
  • + GNU GCC on PowerPC;
    • +
  • + Windows.
+

If your program is single-threaded and does not link to any libraries that might + have used shared_ptr in its default configuration, you can + #define the macro BOOST_SP_DISABLE_THREADS on a + project-wide basis to switch to ordinary non-atomic reference count updates.

+

(Defining BOOST_SP_DISABLE_THREADS in some, but not + all, translation units is technically a violation of the One Definition + Rule and undefined behavior. Nevertheless, the implementation attempts to do + its best to accommodate the request to use non-atomic updates in those + translation units. No guarantees, though.)

+

You can define the macro BOOST_SP_USE_PTHREADS to turn off the + lock-free platform-specific implementation and fall back to the generic + pthread_mutex_t-based code.

Frequently Asked Questions

Q. There are several variations of shared pointers, with different tradeoffs; why does the smart pointer library supply only a single @@ -691,7 +687,7 @@ int * p = a.release();

$Date$

Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. - Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and + Copyright 2002-2005 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/weak_ptr.htm b/weak_ptr.htm index e5ccc11..3fcdcb7 100644 --- a/weak_ptr.htm +++ b/weak_ptr.htm @@ -145,9 +145,9 @@ template<class Y> weak_ptr & operator=(shared_ptr<Y> const &

use_count

long use_count() const;
-

Returns: if *this is empty, an unspecified - nonnegative value; otherwise, the number of shared_ptr objects that share - ownership with *this.

+

Returns: 0 if *this is empty; otherwise, + the number of shared_ptr objects that share ownership + with *this.

Throws: nothing.

Notes: use_count() is not necessarily efficient. Use only for debugging and testing purposes, not for production code.

@@ -236,7 +236,7 @@ public:

$Date$

Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. - Copyright 2002, 2003 Peter Dimov. Permission to copy, use, modify, sell and + Copyright 2002-2005 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.