Smart
+Pointer ChangesSmart
+Pointer ChangesThe February 2002 change to the Boost smart pointers introduced a number +of changes. Since the previous version of the smart pointers was in use for +a long time, it's useful to have a detailed list of what changed from a library +user's point of view.
+ +Note that for compilers that don't support member templates well enough, +a separate implementation is used that lacks many of the new features and is +more like the old version.
+ +Revised 1 February 2002
+ +Copyright 2002 Darin Adler. +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/gccspeed.gif b/gccspeed.gif new file mode 100644 index 0000000..d78c06b Binary files /dev/null and b/gccspeed.gif differ diff --git a/include/boost/detail/atomic_count.hpp b/include/boost/detail/atomic_count.hpp new file mode 100644 index 0000000..6486755 --- /dev/null +++ b/include/boost/detail/atomic_count.hpp @@ -0,0 +1,122 @@ +#ifndef BOOST_DETAIL_ATOMIC_COUNT_HPP_INCLUDED +#define BOOST_DETAIL_ATOMIC_COUNT_HPP_INCLUDED + +#if _MSC_VER >= 1020 +#pragma once +#endif + +// +// boost/detail/atomic_count.hpp - thread/SMP safe reference counter +// +// Copyright (c) 2001, 2002 Peter Dimov and Multi Media Ltd. +// +// Permission to copy, use, modify, sell and distribute this software +// is granted provided this copyright notice appears in all copies. +// This software is provided "as is" without express or implied +// warranty, and with no claim as to its suitability for any purpose. +// +// typedef |
+ Home | +Libraries | +People | +FAQ | +More | +
The smart pointer library includes five smart pointer class templates. Smart +pointers ease the management of memory dynamically allocated with C++ new +expressions. In addition, scoped_ptr can ease the management of memory +dynamically allocated in other ways.
+Revised 1 February 2002.
+ + + + diff --git a/msvcspeed.gif b/msvcspeed.gif new file mode 100644 index 0000000..56295ee Binary files /dev/null and b/msvcspeed.gif differ diff --git a/scoped_array.htm b/scoped_array.htm new file mode 100644 index 0000000..4df98a9 --- /dev/null +++ b/scoped_array.htm @@ -0,0 +1,145 @@ + + + + + + +scoped_array class templateThe scoped_array class template stores a pointer to a dynamically allocated +array. (Dynamically allocated arrays are allocated with the C++ new[] +expression.) The array pointed to is guaranteed to be deleted, +either on destruction of the scoped_array, or via an explicit reset.
+ +The scoped_array template is a simple solution for simple +needs. It supplies a basic "resource acquisition is +initialization" facility, without shared-ownership or transfer-of-ownership +semantics. Both its name and enforcement of semantics (by being +noncopyable) +signal its intent to retain ownership solely within the current scope. +Because it is noncopyable, it is +safer than shared_array for pointers which should not be copied.
+ +Because scoped_array is so simple, in its usual implementation +every operation is as fast as a built-in array pointer and it has no +more space overhead that a built-in array pointer.
+ +It cannot be used in C++ standard library containers. +See shared_array +if scoped_array does not meet your needs.
+ +It cannot correctly hold a pointer to a single object. +See scoped_ptr +for that usage.
+ +A std::vector is an alternative to a scoped_array that is +a bit heavier duty but far more flexible. +A boost::array is an alternative that does not use dynamic allocation.
+ +The class template is parameterized on T, the type of the object +pointed to. T must meet the smart pointer +common requirements.
+ +namespace boost {
+
+ template<typename T> class scoped_array : noncopyable {
+
+ public:
+ typedef T element_type;
+
+ explicit scoped_array(T * p = 0); // never throws
+ ~scoped_array(); // never throws
+
+ void reset(T * p = 0); // never throws
+
+ T & operator[](std::size_t i) const; // never throws
+ T * get() const; // never throws
+
+ void swap(scoped_array & b); // never throws
+ };
+
+ template<typename T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws
+
+}
+
+typedef T element_type;+
Provides the type of the stored pointer.
+ +explicit scoped_array(T * p = 0); // never throws+
Constructs a scoped_array, storing a copy of p, which must +have been allocated via a C++ new[] expression or be 0. +T is not required be a complete type. +See the smart pointer +common requirements.
+ +~scoped_array(); // never throws+
Deletes the array pointed to by the stored pointer. +Note that delete[] on a pointer with a value of 0 is harmless. +The guarantee that this does not throw exceptions depends on the requirement that the +deleted array's objects' destructors do not throw exceptions. +See the smart pointer common requirements.
+ +void reset(T * p = 0); // never throws+
If p is not equal to the stored pointer, deletes the array pointed to by the +stored pointer and then stores a copy of p, which must have been allocated via a +C++ new[] expression or be 0. +The guarantee that this does not throw exceptions depends on the requirement that the +deleted array's objects' destructors do not throw exceptions. +See the smart pointer common requirements.
+ +T & operator[](std::size_t i) const; // never throws+
Returns a reference to element i of the array pointed to by the +stored pointer. +Behavior is undefined and almost certainly undesirable if the stored pointer is 0, +or if i is less than 0 or is greater than or equal to the number of elements +in the array.
+ +T * get() const; // never throws+
Returns the stored pointer. +T need not be a complete type. +See the smart pointer +common requirements.
+ +void swap(scoped_array & b); // never throws+
Exchanges the contents of the two smart pointers. +T need not be a complete type. +See the smart pointer +common requirements.
+ +template<typename T> void swap(scoped_array<T> & a, scoped_array<T> & b); // never throws+
Equivalent to a.swap(b). Matches the interface of std::swap. +Provided as an aid to generic programming.
+ +Revised 1 February 2002
+ +Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. +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/scoped_ptr.htm b/scoped_ptr.htm new file mode 100644 index 0000000..ec0057d --- /dev/null +++ b/scoped_ptr.htm @@ -0,0 +1,217 @@ + + + + + + +scoped_ptr class templateThe scoped_ptr class template stores a pointer to a dynamically allocated +object. (Dynamically allocated objects are allocated with the C++ new +expression.) The object pointed to is guaranteed to be deleted, +either on destruction of the scoped_ptr, or via an explicit reset. +See the example.
+ +The scoped_ptr template is a simple solution for simple +needs. It supplies a basic "resource acquisition is +initialization" facility, without shared-ownership or transfer-of-ownership +semantics. Both its name and enforcement of semantics (by being +noncopyable) +signal its intent to retain ownership solely within the current scope. +Because it is noncopyable, it is +safer than shared_ptr or std::auto_ptr for pointers which should not be +copied.
+ +Because scoped_ptr is simple, in its usual implementation +every operation is as fast as for a built-in pointer and it has no more space overhead +that a built-in pointer.
+ +It cannot be used in C++ Standard Library containers. +See shared_ptr +or std::auto_ptr if scoped_ptr does not meet your needs.
+ +It cannot correctly hold a pointer to a +dynamically allocated array. See scoped_array +for that usage.
+ +The class template is parameterized on T, the type of the object +pointed to. T must meet the smart pointer +common requirements.
+ +namespace boost {
+
+ template<typename T> class scoped_ptr : noncopyable {
+
+ public:
+ typedef T element_type;
+
+ explicit scoped_ptr(T * p = 0); // never throws
+ ~scoped_ptr(); // never throws
+
+ void reset(T * p = 0); // never throws
+
+ T & operator*() const; // never throws
+ T * operator->() const; // never throws
+ T * get() const; // never throws
+
+ void swap(scoped_ptr & b); // never throws
+ };
+
+ template<typename T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & b); // never throws
+
+}
+
+typedef T element_type;+
Provides the type of the stored pointer.
+ +explicit scoped_ptr(T * p = 0); // never throws+
Constructs a scoped_ptr, storing a copy of p, which must +have been allocated via a C++ new expression or be 0. +T is not required be a complete type. +See the smart pointer +common requirements.
+ +~scoped_ptr(); // never throws+
Deletes the object pointed to by the stored pointer. +Note that delete on a pointer with a value of 0 is harmless. +The guarantee that this does not throw exceptions depends on the requirement that the +deleted object's destructor does not throw exceptions. +See the smart pointer common requirements.
+ +void reset(T * p = 0); // never throws+
If p is not equal to the stored pointer, deletes the object pointed to by the +stored pointer and then stores a copy of p, which must have been allocated via a +C++ new expression or be 0. +The guarantee that this does not throw exceptions depends on the requirement that the +deleted object's destructor does not throw exceptions. +See the smart pointer common requirements.
+ +T & operator*() const; // never throws+
Returns a reference to the object pointed to by the stored pointer. +Behavior is undefined if the stored pointer is 0.
+T * operator->() const; // never throws+
Returns the stored pointer. Behavior is undefined if the stored pointer is 0.
+ +T * get() const; // never throws+
Returns the stored pointer. +T need not be a complete type. +See the smart pointer +common requirements.
+ +void swap(scoped_ptr & b); // never throws+
Exchanges the contents of the two smart pointers. +T need not be a complete type. +See the smart pointer +common requirements.
+ +template<typename T> void swap(scoped_ptr<T> & a, scoped_ptr<T> & b); // never throws+
Equivalent to a.swap(b). Matches the interface of std::swap. +Provided as an aid to generic programming.
+ +Here's an example that uses scoped_ptr.
+ +
+#include <boost/scoped_ptr.hpp>
+#include <iostream>
+
+struct Shoe { ~Shoe() { std::cout << "Buckle my shoe\n"; } };
+
+class MyClass {
+ boost::scoped_ptr<int> ptr;
+ public:
+ MyClass() : ptr(new int) { *ptr = 0; }
+ int add_one() { return ++*ptr; }
+};
+
+void main()
+{
+ boost::scoped_ptr<Shoe> x(new Shoe);
+ MyClass my_instance;
+ std::cout << my_instance.add_one() << '\n';
+ std::cout << my_instance.add_one() << '\n';
+}
+
+
+The example program produces the beginning of a child's nursery rhyme:
+ +++ +1 +2 +Buckle my shoe+
The primary reason to use scoped_ptr rather than auto_ptr is to let readers +of your code know that you intend "resource acquisition is initialization" to be applied only +for the current scope, and have no intent to transfer ownership.
+ +A secondary reason to use scoped_ptr is to prevent a later maintenance programmer +from adding a function that transfers ownership by returning the auto_ptr, +because the maintenance programmer saw auto_ptr, and assumed ownership could safely +be transferred.
+ +Think of bool vs int. We all know that under the covers bool is usually +just an int. Indeed, some argued against including bool in the +C++ standard because of that. But by coding bool rather than int, you tell your readers +what your intent is. Same with scoped_ptr; by using it you are signaling intent.
+ +It has been suggested that scoped_ptr<T> is equivalent to +std::auto_ptr<T> const. Ed Brey pointed out, however, that +reset will not work on a std::auto_ptr<T> const.
+ +One common usage of scoped_ptr is to implement a handle/body (also +called pimpl) idiom which avoids exposing the body (implementation) in the header +file.
+ +The scoped_ptr_example_test.cpp +sample program includes a header file, scoped_ptr_example.hpp, +which uses a scoped_ptr<> to an incomplete type to hide the +implementation. The +instantiation of member functions which require a complete type occurs in +the scoped_ptr_example.cpp +implementation file.
+ +Q. Why doesn't scoped_ptr have a release() member?
+A. Because the point of scoped_ptr is to signal intent, not
+to transfer ownership. Use std::auto_ptr if ownership transfer is
+required.
Revised 1 February 2002
+ +Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. +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/scoped_ptr_example.cpp b/scoped_ptr_example.cpp new file mode 100644 index 0000000..3e2e511 --- /dev/null +++ b/scoped_ptr_example.cpp @@ -0,0 +1,16 @@ +// Boost scoped_ptr_example implementation file -----------------------------// + +#include "scoped_ptr_example.hpp" +#includeshared_array class templateThe shared_array class template stores a pointer to a dynamically allocated +array. (Dynamically allocated array are allocated with the C++ new[] +expression.) The object pointed to is guaranteed to be deleted when +the last shared_array pointing to it is destroyed or reset.
+ +Every shared_array 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 shared_array works with +the standard library's associative containers.
+ +Normally, a shared_array cannot correctly hold a pointer to a +dynamically allocated array. See shared_ptr +for that usage.
+ +Because the implementation uses reference counting, shared_array will not work +correctly with cyclic data structures. For example, if main() holds a shared_array +to A, which directly or indirectly holds a shared_array back to A, +A's use count will be 2. Destruction of the original shared_array +will leave A dangling with a use count of 1.
+ +A shared_ptr to a std::vector is an alternative to a shared_array that is +a bit heavier duty but far more flexible.
+ +The class template is parameterized on T, the type of the object +pointed to. T must meet the smart pointer +common requirements.
+ +namespace boost {
+
+ template<typename T> class shared_array {
+
+ public:
+ typedef T element_type;
+
+ explicit shared_array(T * p = 0);
+ template<typename D> shared_array(T * p, D d);
+ ~shared_array(); // never throws
+
+ shared_array(shared_array const & r); // never throws
+
+ shared_array & operator=(shared_array const & r); // never throws
+
+ void reset(T * p = 0); // never throws
+ template<typename D> void reset(T * p, D d); // never throws
+
+ T & operator[](std::ptrdiff_t i) const() const; // never throws
+ T * get() const; // never throws
+
+ bool unique() const; // never throws
+ long use_count() const; // never throws
+
+ void swap(shared_array<T> & b); // never throws
+ };
+
+ template<typename T>
+ bool operator==(shared_array<T> const & a, shared_array<T> const & b); // never throws
+ template<typename T>
+ bool operator!=(shared_array<T> const & a, shared_array<T> const & b); // never throws
+ template<typename T>
+ bool operator<(shared_array<T> const & a, shared_array<T> const & b); // never throws
+
+ template<typename T> void swap(shared_array<T> & a, shared_array<T> & b); // never throws
+
+}
+
+typedef T element_type;+
Provides the type of the stored pointer.
+ +explicit shared_array(T * p = 0);+
Constructs a shared_array, storing a copy of p, which +must be a pointer to an array that was allocated via a C++ new[] expression or be 0. +Afterwards, the use count is 1 (even if p == 0; see ~shared_array). +The only exception which may be thrown by this constructor is std::bad_alloc. +If an exception is thrown, delete[] p is called.
+ +template<typename D> shared_array(T * p, D d);+
Constructs a shared_array, storing a copy of p and of d. +Afterwards, the use count is 1. +D's copy constructor and destructor must not throw. +When the the time comes to delete the array pointed to by p, the object +d is used in the statement d(p). Invoking the object d with +parameter p in this way must not throw. +The only exception which may be thrown by this constructor is std::bad_alloc. +If an exception is thrown, d(p) is called.
+ +shared_array(shared_array const & r); // never throws+
Constructs a shared_array, as if by storing a copy of the +pointer stored in r. Afterwards, the use count +for all copies is 1 more than the initial use count.
+ +~shared_array(); // never throws+
Decrements the use count. Then, if the use count is 0, +deletes the array pointed to by the stored pointer. +Note that delete[] on a pointer with a value of 0 is harmless. +T need not be a complete type. +The guarantee that this does not throw exceptions depends on the requirement that the +deleted object's destructor does not throw exceptions. +See the smart pointer common requirements.
+ +shared_array & operator=(shared_array const & r); // never throws+
Constructs a new shared_array as described above, +then replaces this shared_array with the new one, destroying the replaced object.
+ +void reset(T * p = 0);+
Constructs a new shared_array as described above, +then replaces this shared_array with the new one, destroying the replaced object. +The only exception which may be thrown is std::bad_alloc. If +an exception is thrown, delete[] p is called.
+ +template<typename D> void reset(T * p, D d);+
Constructs a new shared_array as described above, +then replaces this shared_array with the new one, destroying the replaced object. +D's copy constructor must not throw. +The only exception which may be thrown is std::bad_alloc. If +an exception is thrown, d(p) is called.
+ +T & operator[](std::size_t i) const; // never throws+
Returns a reference to element i of the array pointed to by the stored pointer. +Behavior is undefined and almost certainly undesirable if the stored pointer is 0, +or if i is less than 0 or is greater than or equal to the number of elements +in the array.
+ +T * get() const; // never throws+
Returns the stored pointer. +T need not be a complete type. +See the smart pointer +common requirements.
+ +bool unique() const; // never throws+
Returns true if no other shared_array is sharing ownership of +the stored pointer, false otherwise. +T need not be a complete type. +See the smart pointer +common requirements.
+ +long use_count() const; // never throws+
Returns the number of shared_array objects sharing ownership of the +stored pointer. +T need not be a complete type. +See the smart pointer +common requirements.
+Because use_count is not necessarily efficient to implement for +implementations of shared_array that do not use an explicit reference +count, it might be removed from some future version. Thus it should +be used for debugging purposes only, and not production code.
+ +void swap(shared_ptr & b); // never throws+
Exchanges the contents of the two smart pointers. +T need not be a complete type. +See the smart pointer +common requirements.
+ +template<typename T> + bool operator==(shared_array<T> const & a, shared_array<T> const & b); // never throws +template<typename T> + bool operator!=(shared_array<T> const & a, shared_array<T> const & b); // never throws +template<typename T> + bool operator<(shared_array<T> const & a, shared_array<T> const & b); // never throws+
Compares the stored pointers of the two smart pointers. +T need not be a complete type. +See the smart pointer +common requirements.
+The operator< overload is provided to define an ordering so that shared_array +objects can be used in associative containers such as std::map. +The implementation uses std::less<T *> to perform the +comparison. This ensures that the comparison is handled correctly, since the +standard mandates that relational operations on pointers are unspecified (5.9 [expr.rel] +paragraph 2) but std::less<> on pointers is well-defined (20.3.3 [lib.comparisons] +paragraph 8).
+ +template<typename T> + void swap(shared_array<T> & a, shared_array<T> & b) // never throws+
Equivalent to a.swap(b). Matches the interface of std::swap. +Provided as an aid to generic programming.
+ +Revised 1 February 2002
+ +Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. +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/shared_ptr.htm b/shared_ptr.htm new file mode 100644 index 0000000..42e23fe --- /dev/null +++ b/shared_ptr.htm @@ -0,0 +1,356 @@ + + + + + + +shared_ptr class templateIntroduction
+Synopsis
+Members
+Free Functions
+Example
+Handle/Body Idiom
+Frequently Asked Questions
+Smart Pointer Timings
The shared_ptr class template stores a pointer to a dynamically allocated +object. (Dynamically allocated objects are allocated with the 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 requirements of the C++ Standard Library, and so +can be used in standard library containers. Comparison operators +are supplied so that shared_ptr works with +the standard library's associative containers.
+ +Normally, a shared_ptr cannot correctly hold a pointer to a +dynamically allocated array. See shared_array +for that usage.
+ +Because the implementation uses reference counting, shared_ptr will not work +correctly with cyclic data structures. For example, if main() holds a shared_ptr +to A, which directly or indirectly holds a shared_ptr back to A, +A's use count will be 2. Destruction of the original shared_ptr +will leave A dangling with a use count of 1.
+ +The class template is parameterized on T, the type of the object +pointed to. T must meet the smart pointer +common requirements. +T may be void, but in that case, either an explicit delete +function must be passed in, or the pointed-to object must have a trivial destructor.
+ +namespace boost {
+
+ template<typename T> class shared_ptr {
+
+ public:
+ typedef T element_type;
+
+ explicit shared_ptr(T * p = 0);
+ template<typename D> shared_ptr(T * p, D d);
+ ~shared_ptr(); // never throws
+
+ shared_ptr(shared_ptr const & r); // never throws
+ template<typename Y> shared_ptr(shared_ptr<Y> const & r); // never throws
+ template<typename Y> shared_ptr(std::auto_ptr<Y> & r);
+
+ shared_ptr & operator=(shared_ptr const & r); // never throws
+ template<typename Y> shared_ptr & operator=(shared_ptr<Y> const & r); // never throws
+ template<typename Y> shared_ptr & operator=(std::auto_ptr<Y> & r);
+
+ void reset(T * p = 0); // never throws
+ template<typename D> void reset(T * p, D d); // never throws
+
+ T & operator*() const; // never throws
+ T * operator->() const; // never throws
+ T * get() const; // never throws
+
+ bool unique() const; // never throws
+ long use_count() const; // never throws
+
+ void swap(shared_ptr<T> & b); // never throws
+ };
+
+ template<typename T, typename U>
+ bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b); // never throws
+ template<typename T, typename U>
+ bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b); // never throws
+ template<typename T, typename U>
+ bool operator<(shared_ptr<T> const & a, shared_ptr<U> const & b); // never throws
+
+ template<typename T> void swap(shared_ptr<T> & a, shared_ptr<T> & b); // never throws
+
+ template<typename T, typename U>
+ shared_ptr<T> shared_static_cast(shared_ptr<U> const & r); // never throws
+ template<typename T, typename U>
+ shared_ptr<T> shared_dynamic_cast(shared_ptr<U> const & r);
+
+}
+
+typedef T element_type;+
Provides the type of the stored pointer.
+ +explicit shared_ptr(T * p = 0);+
Constructs a shared_ptr, storing a copy of p, which +must be a pointer to an object that was allocated via a C++ new expression or be 0. +Afterwards, the use count is 1 (even if p == 0; see ~shared_ptr). +The only exception which may be thrown by this constructor is std::bad_alloc. +If an exception is thrown, delete p is called.
+ +template<typename D> shared_ptr(T * p, D d);+
Constructs a shared_ptr, storing a copy of p and of d. +Afterwards, the use count is 1. +D's copy constructor and destructor must not throw. +When the the time comes to delete the object pointed to by p, the object +d is used in the statement d(p). Invoking the object d with +parameter p in this way must not throw. +The only exception which may be thrown by this constructor is std::bad_alloc. +If an exception is thrown, d(p) is called.
+ +shared_ptr(shared_ptr const & r); // never throws +template<typename Y> shared_ptr(shared_ptr<Y> const & r); // never throws +template<typename Y> shared_ptr(std::auto_ptr<Y> & r);+
Constructs a shared_ptr, as if by storing a copy of the +pointer stored in r. Afterwards, the use count +for all copies is 1 more than the initial use count, or 1 +in the auto_ptr case. In the auto_ptr case, r.release() +is called. +The only exception which may be thrown is std::bad_alloc, +which may be thrown during construction from auto_ptr. +If an exception is thrown, the constructor has no effect.
+ +~shared_ptr(); // never throws+
Decrements the use count. Then, if the use count is 0, +deletes the object pointed to by the stored pointer. +Note that delete on a pointer with a value of 0 is harmless. +T need not be a complete type. +The guarantee that this does not throw exceptions depends on the requirement that the +deleted object's destructor does not throw exceptions. +See the smart pointer common requirements.
+ +shared_ptr & operator=(shared_ptr const & r); // never throws +template<typename Y> shared_ptr & operator=(shared_ptr<Y> const & r); // never throws +template<typename Y> shared_ptr & operator=(std::auto_ptr<Y> & r);+
Constructs a new shared_ptr as described above, +then replaces this shared_ptr with the new one, destroying the replaced object. +The only exception which may be thrown is std::bad_alloc, +which may be thrown during assignment from auto_ptr. +If an exception is thrown, the assignment has no effect.
+ +void reset(T * p = 0);+
Constructs a new shared_ptr as described above, +then replaces this shared_ptr with the new one, destroying the replaced object. +The only exception which may be thrown is std::bad_alloc. If +an exception is thrown, delete p is called.
+ +template<typename D> void reset(T * p, D d);+
Constructs a new shared_ptr as described above, +then replaces this shared_ptr with the new one, destroying the replaced object. +D's copy constructor must not throw. +The only exception which may be thrown is std::bad_alloc. If +an exception is thrown, d(p) is called.
+ +T & operator*() const; // never throws+
Returns a reference to the object pointed to by the stored pointer. +Behavior is undefined if the stored pointer is 0.
+T * operator->() const; // never throws+
Returns the stored pointer. Behavior is undefined if the stored pointer is 0.
+ +T * get() const; // never throws+
Returns the stored pointer. +T need not be a complete type. +See the smart pointer +common requirements.
+ +bool unique() const; // never throws+
Returns true if no other shared_ptr is sharing ownership of +the stored pointer, false otherwise. +T need not be a complete type. +See the smart pointer +common requirements.
+ +long use_count() const; // never throws+
Returns the number of shared_ptr objects sharing ownership of the +stored pointer. +T need not be a complete type. +See the smart pointer +common requirements.
+Because use_count is not necessarily efficient to implement for +implementations of shared_ptr that do not use an explicit reference +count, it might be removed from some future version. Thus it should +be used for debugging purposes only, and not production code.
+ +void swap(shared_ptr & b); // never throws+
Exchanges the contents of the two smart pointers. +T need not be a complete type. +See the smart pointer +common requirements.
+ +template<typename T, typename U> + bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b); // never throws +template<typename T, typename U> + bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b); // never throws +template<typename T, typename U> + bool operator<(shared_ptr<T> const & a, shared_ptr<U> const & b); // never throws+
Compares the stored pointers of the two smart pointers. +T need not be a complete type. +See the smart pointer +common requirements.
+The operator< overload is provided to define an ordering so that shared_ptr +objects can be used in associative containers such as std::map. +The implementation uses std::less<T *> to perform the +comparison. This ensures that the comparison is handled correctly, since the +standard mandates that relational operations on pointers are unspecified (5.9 [expr.rel] +paragraph 2) but std::less<> on pointers is well-defined (20.3.3 [lib.comparisons] +paragraph 8).
+ +template<typename T> + void swap(shared_ptr<T> & a, shared_ptr<T> & b) // never throws+
Equivalent to a.swap(b). Matches the interface of std::swap. +Provided as an aid to generic programming.
+ +template<typename T, typename U> + shared_ptr<T> shared_static_cast(shared_ptr<U> const & r); // never throws+
Perform a static_cast on the stored pointer, returning another shared_ptr. +The resulting smart pointer will share its use count with the original pointer.
+Note that the seemingly equivalent expression
+shared_ptr<T>(static_cast<T*>(r.get()))will eventually result in undefined behavior, attempting to delete the same object twice.
+ +template<typename T, typename U> + shared_ptr<T> shared_dynamic_cast(shared_ptr<U> const & r);+
Perform a dynamic_cast on the stored pointer, returning another shared_ptr. +The resulting smart pointer will share its use count with the original pointer unless the result of the +cast is 0. The only exception which may be thrown is std::bad_alloc, which may be thrown during the +construction of the new shared_ptr if the result of the cast is 0. If an exception is thrown, the +cast has no effect.
+Note that the seemingly equivalent expression
+shared_ptr<T>(dynamic_cast<T*>(r.get()))will eventually result in undefined behavior, attempting to delete the same object twice.
+ +See shared_ptr_example.cpp for a complete example program. +The program builds a std::vector and std::set of shared_ptr objects.
+ +Note that after the containers have been populated, some of the shared_ptr objects +will have a use count of 1 rather than a use count of 2, since the set is a std::set +rather than a std::multiset, and thus does not contain duplicate entries. +Furthermore, the use count may be even higher +at various times while push_back and insert container operations are performed. +More complicated yet, the container operations may throw exceptions under a +variety of circumstances. Getting the memory management and exception handling in this +example right without a smart pointer would be a nightmare.
+ +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 +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 type occurs in the +shared_ptr_example2.cpp +implementation file. +Note that there is no need for an explicit destructor. +Unlike ~scoped_ptr, ~shared_ptr does not require that T be a complete type.
+ +Q. Why doesn't shared_ptr have template parameters supplying
+traits or policies to allow extensive user customization?
+A. Parameterization discourages users. The shared_ptr template is
+carefully crafted to meet common needs without extensive parameterization.
+Some day a highly configurable smart pointer may be invented that is also very
+easy to use and very hard to misuse. Until then, shared_ptr is the
+smart pointer of choice for a wide range of applications. (Those
+interested in policy based smart pointers should read
+Modern C++ Design by Andrei Alexandrescu.)
Q. Why doesn't shared_ptr use a linked list implementation?
+A. A linked list implementation does not offer enough advantages to
+offset the added cost of an extra pointer. See timings
+page.
Q. Why doesn't shared_ptr (or any of the other Boost smart pointers)
+supply an automatic conversion to T*?
+A. Automatic conversion is believed to be too error prone.
Q. Why does shared_ptr supply use_count()?
+A. As an aid to writing test cases and debugging displays. One of the
+progenitors had use_count(), and it was useful in tracking down bugs in a
+complex project that turned out to have cyclic-dependencies.
Q. Why doesn't shared_ptr specify complexity requirements?
+A. Because complexity requirements limit implementors and complicate the
+specification without apparent benefit to shared_ptr users.
+For example, error-checking implementations might become non-conforming if they
+had to meet stringent complexity requirements.
Q. Why doesn't shared_ptr provide a release() function?
+A. shared_ptr cannot give away ownership unless it's unique()
+because the other copy will still destroy the object.
Consider:
++ +shared_ptr<int> a(new int); +shared_ptr<int> b(a); // a.use_count() == b.use_count() == 2 + +int * p = a.release(); + +// Who owns p now? b will still call delete on it in its destructor.
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.
Revised 1 February 2002
+ +Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. +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/shared_ptr_example.cpp b/shared_ptr_example.cpp new file mode 100644 index 0000000..4db8fc6 --- /dev/null +++ b/shared_ptr_example.cpp @@ -0,0 +1,96 @@ +// Boost shared_ptr_example.cpp --------------------------------------------// + +// (C) Copyright Beman Dawes 2001. Permission to copy, +// use, modify, sell and distribute this software is granted provided this +// copyright notice appears in all copies. This software is provided "as is" +// without express or implied warranty, and with no claim as to its +// suitability for any purpose. + +// See http://www.boost.org for most recent version including documentation. + +// Revision History +// 21 May 01 Initial complete version (Beman Dawes) + +// The original code for this example appeared in the shared_ptr documentation. +// Ray Gallimore pointed out that foo_set was missing a Compare template +// argument, so would not work as intended. At that point the code was +// turned into an actual .cpp file so it could be compiled and tested. + +#includeSmart
+PointersSmart pointers are objects which store pointers to dynamically allocated +(heap) objects. They behave much like built-in C++ pointers except that +they automatically delete the object pointed to at the appropriate +time. Smart pointers are particularly useful in the face of exceptions as +they ensure proper destruction of dynamically allocated objects. They can also +be used to keep track of dynamically allocated objects shared by multiple +owners.
+ +Conceptually, smart pointers are seen as owning the object pointed to, and +thus responsible for deletion of the object when it is no longer needed.
+ +The smart pointer library provides five smart pointer class templates:
+ +| scoped_ptr | +<boost/scoped_ptr.hpp> | +Simple sole ownership of single objects. Noncopyable. | +
| scoped_array | +<boost/scoped_array.hpp> | +Simple sole ownership of arrays. Noncopyable. | +
| shared_ptr | +<boost/shared_ptr.hpp> | +Object ownership shared among multiple pointers | +
| shared_array | +<boost/shared_array.hpp> | +Array ownership shared among multiple pointers. | +
| weak_ptr | +<boost/weak_ptr.hpp> | +Non-owning observers of an object owned by shared_ptr. | +
These templates are designed to complement the std::auto_ptr template.
+ +They are examples of the "resource acquisition is initialization" +idiom described in Bjarne Stroustrup's "The C++ Programming Language", +3rd edition, Section 14.4, Resource Management.
+ +A test program, smart_ptr_test.cpp, is +provided to verify correct operation.
+ +A page on compatibility with older versions of +the Boost smart pointer library describes some of the changes since earlier versions +of the smart pointer implementation.
+ +A page on smart pointer timings will be of +interest to those curious about performance issues.
+ +These smart pointer class templates have a template parameter, T, which +specifies the type of the object pointed to by the smart pointer. The +behavior of the smart pointer templates is undefined if the destructor or operator delete +for objects of type T throw exceptions.
+ +T may be an incomplete type at the point of smart pointer +declaration. Unless otherwise specified, it is required that T +be a complete type at points of smart pointer instantiation. Implementations are +required to diagnose (treat as an error) all violations of this requirement, +including deletion of an incomplete type. +See the description of the checked_delete +function template.
+ +The requirements on T are carefully crafted to maximize safety +yet allow handle-body (also called pimpl) and similar idioms. In these idioms a +smart pointer may appear in translation units where T is an +incomplete type. This separates interface from implementation and hides +implementation from translation units which merely use the interface. +Examples described in the documentation for specific smart pointers illustrate +use of smart pointers in these idioms.
+ +Note that scoped_ptr requires that T be a complete type +at destruction time, but shared_ptr does not.
+ +Several functions in these smart pointer classes are specified as having +"no effect" or "no effect except such-and-such" if an +exception is thrown. This means that when an exception is thrown by +an object of one of these classes, the entire program state remains the same as +it was prior to the function call which resulted in the exception being +thrown. This amounts to a guarantee that there are no detectable side +effects. Other functions never throw exceptions. The only exception +ever thrown by functions which do throw (assuming T meets the +common requirements) is std::bad_alloc, +and that is thrown only by functions which are explicitly documented as possibly +throwing std::bad_alloc.
+ +Exception-specifications are not used; see +exception-specification +rationale.
+ +All the smart pointer templates contain member functions which can never throw exceptions,
+because they neither throw exceptions themselves nor call other functions which
+may throw exceptions. These members are indicated by a comment:
+// never throws.
Functions which destroy objects of the pointed to type are prohibited from +throwing exceptions by the common requirements.
+ +January 2002. Peter Dimov reworked all four classes, adding features, fixing bugs, +and splitting them into four separate headers, and added weak_ptr. See the +compatibility page for a summary of the changes.
+ +May 2001. Vladimir Prus suggested requiring a complete type on +destruction. Refinement evolved in discussions including Dave Abrahams, +Greg Colvin, Beman Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus, +Shankar Sai, and others.
+ +November 1999. Darin Adler provided operator ==, operator !=, and std::swap +and std::less specializations for shared types.
+ +September 1999. Luis Coelho provided shared_ptr::swap and shared_array::swap
+ +May 1999. In April and May, 1999, Valentin Bonnard and David Abrahams +made a number of suggestions resulting in numerous improvements. See the +revision history in smart_ptr.hpp +for the specific changes made as a result of their constructive criticism.
+ +October 1998. In 1994 Greg Colvin proposed to the C++ Standards Committee +classes named auto_ptr and counted_ptr which +were very similar to what we now call scoped_ptr and shared_ptr. +The committee document was 94-168/N0555, Exception Safe Smart Pointers. In +one of the very few cases where the Library Working Group's recommendations were +not followed by the full committee, counted_ptr was rejected +and surprising transfer-of-ownership semantics were added to auto_ptr.
+ +Beman Dawes proposed reviving the original semantics under the names safe_ptr +and counted_ptr at an October, 1998, meeting of Per Andersson, +Matt Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar +Kühl, Nathan Myers, Chichiang Wan and Judy Ward. During the discussion, +the four class names were finalized, it was decided that there was no need to +exactly follow the std::auto_ptr interface, and various +function signatures and semantics were finalized.
+ +Over the next three months, several implementations were considered for shared_ptr, +and discussed on the boost.org mailing +list. The implementation questions revolved around the reference count +which must be kept, either attached to the pointed to object, or detached +elsewhere. Each of those variants have themselves two major variants: + +
Each implementation technique has advantages and disadvantages. We went +so far as to run various timings of the direct and indirect approaches, and +found that at least on Intel Pentium chips there was very little measurable +difference. Kevlin Henney provided a paper he wrote on "Counted Body +Techniques." Dietmar Kühl suggested an elegant partial template +specialization technique to allow users to choose which implementation they +preferred, and that was also experimented with.
+ +But Greg Colvin and Jerry Schwarz argued that "parameterization will +discourage users", and in the end we choose to supply only the direct +implementation.
+ +See the Revision History section of the header for further contributors.
+ +Revised 4 February 2002
+ +Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler. +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/smart_ptr_test.cpp b/smart_ptr_test.cpp new file mode 100644 index 0000000..baee93d --- /dev/null +++ b/smart_ptr_test.cpp @@ -0,0 +1,295 @@ +// smart pointer test program ----------------------------------------------// + +// (C) Copyright Beman Dawes 1998, 1999. Permission to copy, use, modify, sell +// and distribute this software is granted provided this copyright notice +// appears in all copies. This software is provided "as is" without express or +// implied warranty, and with no claim as to its suitability for any purpose. + +// Revision History +// 24 May 01 use Boost test library for error detection, reporting, add tests +// for operations on incomplete types (Beman Dawes) +// 29 Nov 99 added std::swap and associative container tests (Darin Adler) +// 25 Sep 99 added swap tests +// 20 Jul 99 header name changed to .hpp +// 20 Apr 99 additional error tests added. + +#include