New smart pointer documentation. Related clean-up of the smart pointer

library. Changing includes to include the new individual smart pointer
headers. Replacing old smart pointer library with an include of the new
smart pointer headers. Simplify ifdefs that involve the member templates
macros now that BOOST_MSVC6_MEMBER_TEMPLATES is also guaranteed to bet
set for platforms that have full member templates.


[SVN r12647]
This commit is contained in:
Darin Adler
2002-02-02 18:36:12 +00:00
parent d3c76575f9
commit 1a7cd887e4
21 changed files with 1367 additions and 1425 deletions

105
compatibility.htm Normal file
View File

@ -0,0 +1,105 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Smart Pointer Changes</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">Smart
Pointer Changes</h1>
<p>The 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.</p>
<p>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.</p>
<h2>Features Requiring Code Changes to Take Advantage</h2>
<ul>
<li>The smart pointer class templates now each have their own header file.
For compatibility, the
<a href="../../boost/smart_ptr.hpp">&lt;boost/smart_ptr.hpp&gt;</a>
header now includes the headers for the four classic smart pointer class templates.</li>
<li>The <b>weak_ptr</b> template was added.</li>
<li>The new <b>shared_ptr</b> and <b>shared_array</b> relax the requirement that the pointed-to object's
destructor must be visible when instantiating the <b>shared_ptr</b> destructor.
This makes it easier to have shared_ptr members in classes without explicit destructors.</li>
<li>A custom deallocator can be passed in when creating a <b>shared_ptr</b> or <b>shared_array</b>.</li>
<li><b>shared_static_cast</b> and <b>shared_dynamic_cast</b> function templates are
provided which work for <b>shared_ptr</b> and <b>weak_ptr</b> as <b>static_cast</b> and
<b>dynamic_cast</b> do for pointers.</li>
<li>The self-assignment misfeature has been removed from <b>shared_ptr::reset</b>,
although it is still present in <b>scoped_ptr</b>, and in <b>std::auto_ptr</b>.
Calling <b>reset</b> with a pointer to the object that's already owned by the
<b>shared_ptr</b> results in undefined behavior
(an assertion, or eventually a double-delete if assertions are off).</li>
<li>The <b>BOOST_SMART_PTR_CONVERSION</b> feature has been removed.</li>
<li><b>shared_ptr&lt;void&gt;</b> is now allowed.</li>
</ul>
<h2>Features That Improve Robustness</h2>
<ul>
<li>The manipulation of use counts is now thread safe on Windows, Linux, and platforms
that support pthreads. See the
<a href="../../boost/detail/atomic_count.hpp">&lt;boost/detail/atomic_count.hpp&gt;</a>
file for details</li>
<li>The new shared_ptr will always delete the object using the pointer it was originally constructed with.
This prevents subtle problems that could happen if the last <b>shared_ptr</b> was a pointer to a sub-object
of a class that did not have a virtual destructor.</li>
</ul>
<h2>Implementation Details</h2>
<ul>
<li>Some bugs in the assignment operator implementations and in <b>reset</b>
have been fixed by using the &quot;copy and swap&quot; idiom.</li>
<li>Assertions have been added to check preconditions of various functions;
however, since these use the new
<a href="../../boost/assert.hpp">&lt;boost/assert.hpp&gt;</a>
header, the assertions are disabled by default.</li>
<li>The partial specialization of <b>std::less</b> has been replaced by <b>operator&lt;</b>
overloads which accomplish the same thing without relying on undefined behavior.</li>
<li>The incorrect overload of <b>std::swap</b> has been replaced by <b>boost::swap</b>, which
has many of the same advantages for generic programming but does not violate the C++ standard.</li>
</ul>
<hr>
<p>Revised 1 February 2002</p>
<p>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 &quot;as is&quot;
without express or implied warranty, and with no claim as to its suitability for
any purpose.</p>
</body>
</html>

View File

@ -35,49 +35,49 @@ public:
typedef T element_type; typedef T element_type;
explicit scoped_array( T* p = 0 ): ptr(p) // never throws explicit scoped_array(T * p = 0) : ptr(p) // never throws
{ {
} }
~scoped_array() ~scoped_array() // never throws
{ {
typedef char type_must_be_complete[sizeof(T)]; typedef char type_must_be_complete[sizeof(T)];
delete [] ptr; delete [] ptr;
} }
void reset( T* p = 0 ) void reset(T * p = 0) // never throws
{ {
typedef char type_must_be_complete[sizeof(T)]; typedef char type_must_be_complete[sizeof(T)];
if ( ptr != p ) if (ptr != p)
{ {
delete [] ptr; delete [] ptr;
ptr = p; ptr = p;
} }
} }
T& operator[](std::ptrdiff_t i) const // never throws T& operator[](std::ptrdiff_t i) const // never throws
{ {
BOOST_ASSERT(ptr != 0); BOOST_ASSERT(ptr != 0);
BOOST_ASSERT(i >= 0); BOOST_ASSERT(i >= 0);
return ptr[i]; return ptr[i];
} }
T* get() const // never throws T* get() const // never throws
{ {
return ptr; return ptr;
} }
void swap(scoped_array & rhs) void swap(scoped_array & b) // never throws
{ {
T * tmp = rhs.ptr; T * tmp = b.ptr;
rhs.ptr = ptr; b.ptr = ptr;
ptr = tmp; ptr = tmp;
} }
}; };
template<class T> inline void swap(scoped_array<T> & a, scoped_array<T> & b) template<class T> inline void swap(scoped_array<T> & a, scoped_array<T> & b) // never throws
{ {
a.swap(b); a.swap(b);
} }

View File

@ -18,7 +18,7 @@ namespace boost
// scoped_ptr mimics a built-in pointer except that it guarantees deletion // scoped_ptr mimics a built-in pointer except that it guarantees deletion
// of the object pointed to, either on destruction of the scoped_ptr or via // of the object pointed to, either on destruction of the scoped_ptr or via
// an explicit reset(). scoped_ptr is a simple solution for simple needs; // an explicit reset(). scoped_ptr is a simple solution for simple needs;
// use shared_ptr or std::auto_ptr if your needs are more complex. // use shared_ptr or std::auto_ptr if your needs are more complex.
template<typename T> class scoped_ptr // noncopyable template<typename T> class scoped_ptr // noncopyable
@ -34,57 +34,57 @@ public:
typedef T element_type; typedef T element_type;
explicit scoped_ptr( T* p = 0 ): ptr(p) // never throws explicit scoped_ptr(T * p = 0): ptr(p) // never throws
{ {
} }
~scoped_ptr() ~scoped_ptr() // never throws
{ {
typedef char type_must_be_complete[sizeof(T)]; typedef char type_must_be_complete[sizeof(T)];
delete ptr; delete ptr;
} }
void reset( T* p = 0 ) void reset(T * p = 0) // never throws
{ {
typedef char type_must_be_complete[sizeof(T)]; typedef char type_must_be_complete[sizeof(T)];
if ( ptr != p ) if (ptr != p)
{ {
delete ptr; delete ptr;
ptr = p; ptr = p;
} }
} }
T& operator*() const // never throws T & operator*() const // never throws
{ {
BOOST_ASSERT(ptr != 0); BOOST_ASSERT(ptr != 0);
return *ptr; return *ptr;
} }
T* operator->() const // never throws T * operator->() const // never throws
{ {
BOOST_ASSERT(ptr != 0); BOOST_ASSERT(ptr != 0);
return ptr; return ptr;
} }
T* get() const // never throws T * get() const // never throws
{ {
return ptr; return ptr;
} }
void swap(scoped_ptr & rhs) void swap(scoped_ptr & b) // never throws
{ {
T * tmp = rhs.ptr; T * tmp = b.ptr;
rhs.ptr = ptr; b.ptr = ptr;
ptr = tmp; ptr = tmp;
} }
}; };
template<class T> inline void swap(scoped_ptr<T> & a, scoped_ptr<T> & b) template<typename T> inline void swap(scoped_ptr<T> & a, scoped_ptr<T> & b) // never throws
{ {
a.swap(b); a.swap(b);
} }
} // namespace boost } // namespace boost
#endif // #ifndef BOOST_SCOPED_PTR_HPP_INCLUDED #endif // #ifndef BOOST_SCOPED_PTR_HPP_INCLUDED

View File

@ -17,7 +17,7 @@
#include <boost/config.hpp> // for broken compiler workarounds #include <boost/config.hpp> // for broken compiler workarounds
#if defined(BOOST_NO_MEMBER_TEMPLATES) && !defined(BOOST_MSVC6_MEMBER_TEMPLATES) #ifndef BOOST_MSVC6_MEMBER_TEMPLATES
#include <boost/detail/shared_array_nmt.hpp> #include <boost/detail/shared_array_nmt.hpp>
#else #else
@ -75,6 +75,11 @@ public:
this_type(p).swap(*this); this_type(p).swap(*this);
} }
template <typename D> void reset(T * p = 0, D d)
{
this_type(p, d).swap(*this);
}
T & operator[] (std::ptrdiff_t i) const // never throws T & operator[] (std::ptrdiff_t i) const // never throws
{ {
BOOST_ASSERT(px != 0); BOOST_ASSERT(px != 0);
@ -87,16 +92,16 @@ public:
return px; return px;
} }
long use_count() const // never throws
{
return pn.use_count();
}
bool unique() const // never throws bool unique() const // never throws
{ {
return pn.unique(); return pn.unique();
} }
long use_count() const // never throws
{
return pn.use_count();
}
void swap(shared_array<T> & other) // never throws void swap(shared_array<T> & other) // never throws
{ {
std::swap(px, other.px); std::swap(px, other.px);
@ -110,28 +115,28 @@ private:
}; // shared_array }; // shared_array
template<class T, class U> inline bool operator==(shared_array<T> const & a, shared_array<U> const & b) template<typename T> inline bool operator==(shared_array<T> const & a, shared_array<T> const & b) // never throws
{ {
return a.get() == b.get(); return a.get() == b.get();
} }
template<class T, class U> inline bool operator!=(shared_array<T> const & a, shared_array<U> const & b) template<typename T> inline bool operator!=(shared_array<T> const & a, shared_array<T> const & b) // never throws
{ {
return a.get() != b.get(); return a.get() != b.get();
} }
template<class T> inline bool operator<(shared_array<T> const & a, shared_array<T> const & b) template<typename T> inline bool operator<(shared_array<T> const & a, shared_array<T> const & b) // never throws
{ {
return std::less<T*>()(a.get(), b.get()); return std::less<T*>()(a.get(), b.get());
} }
template<class T> void swap(shared_array<T> & a, shared_array<T> & b) template<typename T> void swap(shared_array<T> & a, shared_array<T> & b) // never throws
{ {
a.swap(b); a.swap(b);
} }
} // namespace boost } // namespace boost
#endif // #if defined(BOOST_NO_MEMBER_TEMPLATES) && !defined(BOOST_MSVC_MEMBER_TEMPLATES) #endif // #ifndef BOOST_MSVC6_MEMBER_TEMPLATES
#endif // #ifndef BOOST_SHARED_ARRAY_HPP_INCLUDED #endif // #ifndef BOOST_SHARED_ARRAY_HPP_INCLUDED

View File

@ -17,7 +17,7 @@
#include <boost/config.hpp> // for broken compiler workarounds #include <boost/config.hpp> // for broken compiler workarounds
#if defined(BOOST_NO_MEMBER_TEMPLATES) && !defined(BOOST_MSVC6_MEMBER_TEMPLATES) #ifndef BOOST_MSVC6_MEMBER_TEMPLATES
#include <boost/detail/shared_ptr_nmt.hpp> #include <boost/detail/shared_ptr_nmt.hpp>
#else #else
@ -44,7 +44,7 @@ namespace detail
struct static_cast_tag {}; struct static_cast_tag {};
struct dynamic_cast_tag {}; struct dynamic_cast_tag {};
template<class T> struct shared_ptr_traits template<typename T> struct shared_ptr_traits
{ {
typedef T & reference; typedef T & reference;
}; };
@ -108,10 +108,8 @@ public:
template<typename Y> template<typename Y>
shared_ptr(shared_ptr<Y> const & r, detail::dynamic_cast_tag): px(dynamic_cast<element_type *>(r.px)), pn(r.pn) shared_ptr(shared_ptr<Y> const & r, detail::dynamic_cast_tag): px(dynamic_cast<element_type *>(r.px)), pn(r.pn)
{ {
if(px == 0) // need to allocate new counter -- the cast failed if (px == 0) // need to allocate new counter -- the cast failed
{
pn = detail::shared_count(static_cast<element_type *>(0), deleter()); pn = detail::shared_count(static_cast<element_type *>(0), deleter());
}
} }
#ifndef BOOST_NO_AUTO_PTR #ifndef BOOST_NO_AUTO_PTR
@ -124,7 +122,7 @@ public:
#endif #endif
template<typename Y> template<typename Y>
shared_ptr & operator=(shared_ptr<Y> const & r) // nothrow? shared_ptr & operator=(shared_ptr<Y> const & r) // never throws
{ {
px = r.px; px = r.px;
pn = r.pn; // shared_count::op= doesn't throw pn = r.pn; // shared_count::op= doesn't throw
@ -170,16 +168,16 @@ public:
return px; return px;
} }
long use_count() const // never throws
{
return pn.use_count();
}
bool unique() const // never throws bool unique() const // never throws
{ {
return pn.unique(); return pn.unique();
} }
long use_count() const // never throws
{
return pn.use_count();
}
void swap(shared_ptr<T> & other) // never throws void swap(shared_ptr<T> & other) // never throws
{ {
std::swap(px, other.px); std::swap(px, other.px);
@ -204,39 +202,39 @@ private:
}; // shared_ptr }; // shared_ptr
template<class T, class U> inline bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b) template<typename T, typename U> inline bool operator==(shared_ptr<T> const & a, shared_ptr<U> const & b)
{ {
return a.get() == b.get(); return a.get() == b.get();
} }
template<class T, class U> inline bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b) template<typename T, typename U> inline bool operator!=(shared_ptr<T> const & a, shared_ptr<U> const & b)
{ {
return a.get() != b.get(); return a.get() != b.get();
} }
template<class T> inline bool operator<(shared_ptr<T> const & a, shared_ptr<T> const & b) template<typename T> inline bool operator<(shared_ptr<T> const & a, shared_ptr<T> const & b)
{ {
return std::less<T*>()(a.get(), b.get()); return std::less<T*>()(a.get(), b.get());
} }
template<class T, class U> shared_ptr<T> shared_static_cast(shared_ptr<U> const & r) template<typename T> void swap(shared_ptr<T> & a, shared_ptr<T> & b)
{
return shared_ptr<T>(r, detail::static_cast_tag());
}
template<class T, class U> shared_ptr<T> shared_dynamic_cast(shared_ptr<U> const & r)
{
return shared_ptr<T>(r, detail::dynamic_cast_tag());
}
template<class T> void swap(shared_ptr<T> & a, shared_ptr<T> & b)
{ {
a.swap(b); a.swap(b);
} }
template<typename T, typename U> shared_ptr<T> shared_static_cast(shared_ptr<U> const & r)
{
return shared_ptr<T>(r, detail::static_cast_tag());
}
template<typename T, typename U> shared_ptr<T> shared_dynamic_cast(shared_ptr<U> const & r)
{
return shared_ptr<T>(r, detail::dynamic_cast_tag());
}
// get_pointer() enables boost::mem_fn to recognize shared_ptr // get_pointer() enables boost::mem_fn to recognize shared_ptr
template<class T> inline T * get_pointer(shared_ptr<T> const & p) template<typename T> inline T * get_pointer(shared_ptr<T> const & p)
{ {
return p.get(); return p.get();
} }
@ -247,6 +245,6 @@ template<class T> inline T * get_pointer(shared_ptr<T> const & p)
# pragma warning(pop) # pragma warning(pop)
#endif #endif
#endif // #if defined(BOOST_NO_MEMBER_TEMPLATES) && !defined(BOOST_MSVC_MEMBER_TEMPLATES) #endif // #ifndef BOOST_MSVC6_MEMBER_TEMPLATES
#endif // #ifndef BOOST_SHARED_PTR_HPP_INCLUDED #endif // #ifndef BOOST_SHARED_PTR_HPP_INCLUDED

View File

@ -1,402 +1,9 @@
// Boost smart_ptr.hpp header file -----------------------------------------// // Boost smart_ptr.hpp header file -----------------------------------------//
// (C) Copyright Greg Colvin and Beman Dawes 1998, 1999. Permission to copy, // For compatibility, this header includes the header for the four "classic"
// use, modify, sell and distribute this software is granted provided this // smart pointer class templates.
// 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
// 6 Jul 01 Reorder shared_ptr code so VC++ 6 member templates work, allowing
// polymorphic pointers to now work with that compiler (Gary Powell)
// 21 May 01 Require complete type where incomplete type is unsafe.
// (suggested by Vladimir Prus)
// 21 May 01 operator= fails if operand transitively owned by *this, as in a
// linked list (report by Ken Johnson, fix by Beman Dawes)
// 21 Jan 01 Suppress some useless warnings with MSVC (David Abrahams)
// 19 Oct 00 Make shared_ptr ctor from auto_ptr explicit. (Robert Vugts)
// 24 Jul 00 Change throw() to // never throws. See lib guidelines
// Exception-specification rationale. (Beman Dawes)
// 22 Jun 00 Remove #if continuations to fix GCC 2.95.2 problem (Beman Dawes)
// 1 Feb 00 Additional shared_ptr BOOST_NO_MEMBER_TEMPLATES workarounds
// (Dave Abrahams)
// 31 Dec 99 Condition tightened for no member template friend workaround
// (Dave Abrahams)
// 30 Dec 99 Moved BOOST_NMEMBER_TEMPLATES compatibility code to config.hpp
// (Dave Abrahams)
// 30 Nov 99 added operator ==, operator !=, and std::swap and std::less
// specializations for shared types (Darin Adler)
// 11 Oct 99 replaced op[](int) with op[](std::size_t) (Ed Brey, Valentin
// Bonnard), added shared_ptr workaround for no member template
// friends (Matthew Langston)
// 25 Sep 99 added shared_ptr::swap and shared_array::swap (Luis Coelho).
// 20 Jul 99 changed name to smart_ptr.hpp, #include <boost/config.hpp>,
// #include <boost/utility.hpp> and use boost::noncopyable
// 17 May 99 remove scoped_array and shared_array operator*() as
// unnecessary (Beman Dawes)
// 14 May 99 reorder code so no effects when bad_alloc thrown (Abrahams/Dawes)
// 13 May 99 remove certain throw() specifiers to avoid generated try/catch
// code cost (Beman Dawes)
// 11 May 99 get() added, conversion to T* placed in macro guard (Valentin
// Bonnard, Dave Abrahams, and others argued for elimination
// of the automatic conversion)
// 28 Apr 99 #include <memory> fix (Valentin Bonnard)
// 28 Apr 99 rename transfer() to share() for clarity (Dave Abrahams)
// 28 Apr 99 remove unsafe shared_array template conversions(Valentin Bonnard)
// 28 Apr 99 p(r) changed to p(r.px) for clarity (Dave Abrahams)
// 21 Apr 99 reset() self assignment fix (Valentin Bonnard)
// 21 Apr 99 dispose() provided to improve clarity (Valentin Bonnard)
// 27 Apr 99 leak when new throws fixes (Dave Abrahams)
// 21 Oct 98 initial Version (Greg Colvin/Beman Dawes)
#ifndef BOOST_SMART_PTR_HPP
#define BOOST_SMART_PTR_HPP
#include <boost/config.hpp> // for broken compiler workarounds
#include <cstddef> // for std::size_t
#include <memory> // for std::auto_ptr
#include <algorithm> // for std::swap
#include <boost/utility.hpp> // for boost::noncopyable, checked_delete, checked_array_delete
#include <functional> // for std::less
#include <boost/static_assert.hpp> // for BOOST_STATIC_ASSERT
#ifdef BOOST_MSVC // moved here to work around VC++ compiler crash
# pragma warning(push)
# pragma warning(disable:4284) // return type for 'identifier::operator->' is not a UDT or reference to a UDT. Will produce errors if applied using infix notation
#endif
namespace boost {
// scoped_ptr --------------------------------------------------------------//
// scoped_ptr mimics a built-in pointer except that it guarantees deletion
// of the object pointed to, either on destruction of the scoped_ptr or via
// an explicit reset(). scoped_ptr is a simple solution for simple needs;
// see shared_ptr (below) or std::auto_ptr if your needs are more complex.
template<typename T> class scoped_ptr : noncopyable {
T* ptr;
public:
typedef T element_type;
explicit scoped_ptr( T* p=0 ) : ptr(p) {} // never throws
~scoped_ptr() { checked_delete(ptr); }
void reset( T* p=0 ) { if ( ptr != p ) { checked_delete(ptr); ptr = p; } }
T& operator*() const { return *ptr; } // never throws
T* operator->() const { return ptr; } // never throws
T* get() const { return ptr; } // never throws
#ifdef BOOST_SMART_PTR_CONVERSION
// get() is safer! Define BOOST_SMART_PTR_CONVERSION at your own risk!
operator T*() const { return ptr; } // never throws
#endif
}; // scoped_ptr
// scoped_array ------------------------------------------------------------//
// scoped_array extends scoped_ptr to arrays. Deletion of the array pointed to
// is guaranteed, either on destruction of the scoped_array or via an explicit
// reset(). See shared_array or std::vector if your needs are more complex.
template<typename T> class scoped_array : noncopyable {
T* ptr;
public:
typedef T element_type;
explicit scoped_array( T* p=0 ) : ptr(p) {} // never throws
~scoped_array() { checked_array_delete(ptr); }
void reset( T* p=0 ) { if ( ptr != p )
{checked_array_delete(ptr); ptr=p;} }
T* get() const { return ptr; } // never throws
#ifdef BOOST_SMART_PTR_CONVERSION
// get() is safer! Define BOOST_SMART_PTR_CONVERSION at your own risk!
operator T*() const { return ptr; } // never throws
#else
T& operator[](std::size_t i) const { return ptr[i]; } // never throws
#endif
}; // scoped_array
// shared_ptr --------------------------------------------------------------//
// An enhanced relative of scoped_ptr with reference counted copy semantics.
// The object pointed to is deleted when the last shared_ptr pointing to it
// is destroyed or reset.
template<typename T> class shared_ptr {
public:
typedef T element_type;
explicit shared_ptr(T* p =0) : px(p) {
try { pn = new long(1); } // fix: prevent leak if new throws
catch (...) { checked_delete(p); throw; }
}
~shared_ptr() { dispose(); }
#if !defined( BOOST_NO_MEMBER_TEMPLATES ) || defined (BOOST_MSVC6_MEMBER_TEMPLATES)
template<typename Y>
shared_ptr(const shared_ptr<Y>& r) : px(r.px) { // never throws
++*(pn = r.pn);
}
#ifndef BOOST_NO_AUTO_PTR
template<typename Y>
explicit shared_ptr(std::auto_ptr<Y>& r) {
pn = new long(1); // may throw
px = r.release(); // fix: moved here to stop leak if new throws
}
#endif
template<typename Y>
shared_ptr& operator=(const shared_ptr<Y>& r) {
share(r.px,r.pn);
return *this;
}
#ifndef BOOST_NO_AUTO_PTR
template<typename Y>
shared_ptr& operator=(std::auto_ptr<Y>& r) {
// code choice driven by guarantee of "no effect if new throws"
if (*pn == 1) { checked_delete(px); }
else { // allocate new reference counter
long * tmp = new long(1); // may throw
--*pn; // only decrement once danger of new throwing is past
pn = tmp;
} // allocate new reference counter
px = r.release(); // fix: moved here so doesn't leak if new throws
return *this;
}
#endif
#else
#ifndef BOOST_NO_AUTO_PTR
explicit shared_ptr(std::auto_ptr<T>& r) {
pn = new long(1); // may throw
px = r.release(); // fix: moved here to stop leak if new throws
}
shared_ptr& operator=(std::auto_ptr<T>& r) {
// code choice driven by guarantee of "no effect if new throws"
if (*pn == 1) { checked_delete(px); }
else { // allocate new reference counter
long * tmp = new long(1); // may throw
--*pn; // only decrement once danger of new throwing is past
pn = tmp;
} // allocate new reference counter
px = r.release(); // fix: moved here so doesn't leak if new throws
return *this;
}
#endif
#endif
// The assignment operator and the copy constructor must come after
// the templated versions for MSVC6 to work. (Gary Powell)
shared_ptr(const shared_ptr& r) : px(r.px) { ++*(pn = r.pn); } // never throws
shared_ptr& operator=(const shared_ptr& r) {
share(r.px,r.pn);
return *this;
}
void reset(T* p=0) {
if ( px == p ) return; // fix: self-assignment safe
if (--*pn == 0) { checked_delete(px); }
else { // allocate new reference counter
try { pn = new long; } // fix: prevent leak if new throws
catch (...) {
++*pn; // undo effect of --*pn above to meet effects guarantee
checked_delete(p);
throw;
} // catch
} // allocate new reference counter
*pn = 1;
px = p;
} // reset
T& operator*() const { return *px; } // never throws
T* operator->() const { return px; } // never throws
T* get() const { return px; } // never throws
#ifdef BOOST_SMART_PTR_CONVERSION
// get() is safer! Define BOOST_SMART_PTR_CONVERSION at your own risk!
operator T*() const { return px; } // never throws
#endif
long use_count() const { return *pn; } // never throws
bool unique() const { return *pn == 1; } // never throws
void swap(shared_ptr<T>& other) // never throws
{ std::swap(px,other.px); std::swap(pn,other.pn); }
// Tasteless as this may seem, making all members public allows member templates
// to work in the absence of member template friends. (Matthew Langston)
// Don't split this line into two; that causes problems for some GCC 2.95.2 builds
#if ( defined(BOOST_NO_MEMBER_TEMPLATES) && !defined(BOOST_MSVC6_MEMBER_TEMPLATES) ) || !defined( BOOST_NO_MEMBER_TEMPLATE_FRIENDS )
private:
#endif
T* px; // contained pointer
long* pn; // ptr to reference counter
// Don't split this line into two; that causes problems for some GCC 2.95.2 builds
#if !defined( BOOST_NO_MEMBER_TEMPLATES ) && !defined( BOOST_NO_MEMBER_TEMPLATE_FRIENDS )
template<typename Y> friend class shared_ptr;
#endif
void dispose() { if (--*pn == 0) { checked_delete(px); delete pn; } }
void share(T* rpx, long* rpn) {
if (pn != rpn) { // Q: why not px != rpx? A: fails when both == 0
++*rpn; // done before dispose() in case rpn transitively
// dependent on *this (bug reported by Ken Johnson)
dispose();
px = rpx;
pn = rpn;
}
} // share
}; // shared_ptr
template<typename T, typename U>
inline bool operator==(const shared_ptr<T>& a, const shared_ptr<U>& b)
{ return a.get() == b.get(); }
template<typename T, typename U>
inline bool operator!=(const shared_ptr<T>& a, const shared_ptr<U>& b)
{ return a.get() != b.get(); }
// shared_array ------------------------------------------------------------//
// shared_array extends shared_ptr to arrays.
// The array pointed to is deleted when the last shared_array pointing to it
// is destroyed or reset.
template<typename T> class shared_array {
public:
typedef T element_type;
explicit shared_array(T* p =0) : px(p) {
try { pn = new long(1); } // fix: prevent leak if new throws
catch (...) { checked_array_delete(p); throw; }
}
shared_array(const shared_array& r) : px(r.px) // never throws
{ ++*(pn = r.pn); }
~shared_array() { dispose(); }
shared_array& operator=(const shared_array& r) {
if (pn != r.pn) { // Q: why not px != r.px? A: fails when both px == 0
++*r.pn; // done before dispose() in case r.pn transitively
// dependent on *this (bug reported by Ken Johnson)
dispose();
px = r.px;
pn = r.pn;
}
return *this;
} // operator=
void reset(T* p=0) {
if ( px == p ) return; // fix: self-assignment safe
if (--*pn == 0) { checked_array_delete(px); }
else { // allocate new reference counter
try { pn = new long; } // fix: prevent leak if new throws
catch (...) {
++*pn; // undo effect of --*pn above to meet effects guarantee
checked_array_delete(p);
throw;
} // catch
} // allocate new reference counter
*pn = 1;
px = p;
} // reset
T* get() const { return px; } // never throws
#ifdef BOOST_SMART_PTR_CONVERSION
// get() is safer! Define BOOST_SMART_PTR_CONVERSION at your own risk!
operator T*() const { return px; } // never throws
#else
T& operator[](std::size_t i) const { return px[i]; } // never throws
#endif
long use_count() const { return *pn; } // never throws
bool unique() const { return *pn == 1; } // never throws
void swap(shared_array<T>& other) // never throws
{ std::swap(px,other.px); std::swap(pn,other.pn); }
private:
T* px; // contained pointer
long* pn; // ptr to reference counter
void dispose() { if (--*pn == 0) { checked_array_delete(px); delete pn; } }
}; // shared_array
template<typename T>
inline bool operator==(const shared_array<T>& a, const shared_array<T>& b)
{ return a.get() == b.get(); }
template<typename T>
inline bool operator!=(const shared_array<T>& a, const shared_array<T>& b)
{ return a.get() != b.get(); }
} // namespace boost
// specializations for things in namespace std -----------------------------//
#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
namespace std {
// Specialize std::swap to use the fast, non-throwing swap that's provided
// as a member function instead of using the default algorithm which creates
// a temporary and uses assignment.
template<typename T>
inline void swap(boost::shared_ptr<T>& a, boost::shared_ptr<T>& b)
{ a.swap(b); }
template<typename T>
inline void swap(boost::shared_array<T>& a, boost::shared_array<T>& b)
{ a.swap(b); }
// Specialize std::less so we can use shared pointers and arrays as keys in
// associative collections.
// It's still a controversial question whether this is better than supplying
// a full range of comparison operators (<, >, <=, >=).
template<typename T>
struct less< boost::shared_ptr<T> >
: binary_function<boost::shared_ptr<T>, boost::shared_ptr<T>, bool>
{
bool operator()(const boost::shared_ptr<T>& a,
const boost::shared_ptr<T>& b) const
{ return std::less<T*>()(a.get(),b.get()); }
};
template<typename T>
struct less< boost::shared_array<T> >
: binary_function<boost::shared_array<T>, boost::shared_array<T>, bool>
{
bool operator()(const boost::shared_array<T>& a,
const boost::shared_array<T>& b) const
{ return std::less<T*>()(a.get(),b.get()); }
};
} // namespace std
#endif // ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
#ifdef BOOST_MSVC
# pragma warning(pop)
#endif
#endif // BOOST_SMART_PTR_HPP
#include <boost/scoped_ptr.hpp>
#include <boost/scoped_array.hpp>
#include <boost/shared_ptr.hpp>
#include <boost/shared_array.hpp>

View File

@ -67,14 +67,20 @@ public:
template<typename Y> template<typename Y>
weak_ptr(weak_ptr<Y> const & r, detail::dynamic_cast_tag): px(dynamic_cast<element_type *>(r.px)), pn(r.pn) weak_ptr(weak_ptr<Y> const & r, detail::dynamic_cast_tag): px(dynamic_cast<element_type *>(r.px)), pn(r.pn)
{ {
if(px == 0) // need to allocate new counter -- the cast failed if (px == 0) // need to allocate new counter -- the cast failed
{
pn = detail::weak_count(); pn = detail::weak_count();
}
} }
template<typename Y> template<typename Y>
weak_ptr & operator=(weak_ptr<Y> const & r) // nothrow? weak_ptr & operator=(weak_ptr<Y> const & r) // never throws
{
px = r.px;
pn = r.pn;
return *this;
}
template<typename Y>
weak_ptr & operator=(shared_ptr<Y> const & r) // never throws
{ {
px = r.px; px = r.px;
pn = r.pn; pn = r.pn;
@ -86,11 +92,6 @@ public:
this_type().swap(*this); this_type().swap(*this);
} }
long use_count() const // never throws
{
return pn.use_count();
}
T * get() const // never throws T * get() const // never throws
{ {
return use_count() == 0? 0: px; return use_count() == 0? 0: px;
@ -99,7 +100,6 @@ public:
typename detail::shared_ptr_traits<T>::reference operator* () const // never throws typename detail::shared_ptr_traits<T>::reference operator* () const // never throws
{ {
T * p = get(); T * p = get();
BOOST_ASSERT(p != 0); BOOST_ASSERT(p != 0);
return *p; return *p;
} }
@ -107,11 +107,15 @@ public:
T * operator-> () const // never throws T * operator-> () const // never throws
{ {
T * p = get(); T * p = get();
BOOST_ASSERT(p != 0); BOOST_ASSERT(p != 0);
return p; return p;
} }
long use_count() const // never throws
{
return pn.use_count();
}
void swap(weak_ptr<T> & other) // never throws void swap(weak_ptr<T> & other) // never throws
{ {
std::swap(px, other.px); std::swap(px, other.px);
@ -149,6 +153,11 @@ template<class T> inline bool operator<(weak_ptr<T> const & a, weak_ptr<T> const
return std::less<T*>()(a.get(), b.get()); return std::less<T*>()(a.get(), b.get());
} }
template<class T> void swap(weak_ptr<T> & a, weak_ptr<T> & b)
{
a.swap(b);
}
template<class T, class U> weak_ptr<T> shared_static_cast(weak_ptr<U> const & r) template<class T, class U> weak_ptr<T> shared_static_cast(weak_ptr<U> const & r)
{ {
return weak_ptr<T>(r, detail::static_cast_tag()); return weak_ptr<T>(r, detail::static_cast_tag());
@ -159,11 +168,6 @@ template<class T, class U> weak_ptr<T> shared_dynamic_cast(weak_ptr<U> const & r
return weak_ptr<T>(r, detail::dynamic_cast_tag()); return weak_ptr<T>(r, detail::dynamic_cast_tag());
} }
template<class T> void swap(weak_ptr<T> & a, weak_ptr<T> & b)
{
a.swap(b);
}
// get_pointer() enables boost::mem_fn to recognize weak_ptr // get_pointer() enables boost::mem_fn to recognize weak_ptr
template<class T> inline T * get_pointer(weak_ptr<T> const & p) template<class T> inline T * get_pointer(weak_ptr<T> const & p)

View File

@ -1,10 +1,10 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Boost Smart Pointer Library</title> <title>Boost Smart Pointer Library</title>
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
</head> </head>
<body bgcolor="#FFFFFF" text="#000000"> <body bgcolor="#FFFFFF" text="#000000">
@ -19,19 +19,28 @@
<td><a href="../../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td> <td><a href="../../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More</big></font></a></td>
</tr> </tr>
</table> </table>
<h1>Smart pointer library</h1> <h1>Smart Pointer Library</h1>
<p>The header smart_ptr.hpp provides four smart pointer classes.&nbsp; Smart <p>The smart pointer library includes five smart pointer class templates. Smart
pointers ease the management of memory dynamically allocated with C++ <strong>new</strong> pointers ease the management of memory dynamically allocated with C++ <b>new</b>
expressions. expressions. In addition, <b>scoped_ptr</b> can ease the management of memory
dynamically allocated in other ways.</p>
<ul> <ul>
<li><a href="smart_ptr.htm">Documentation</a> (HTML).</li> <li><a href="smart_ptr.htm">Documentation</a> (HTML).</li>
<li>Header <a href="../../boost/smart_ptr.hpp">smart_ptr.hpp</a></li> <li>Header <a href="../../boost/scoped_ptr.hpp">scoped_ptr.hpp</a>.</li>
<li>Header <a href="../../boost/scoped_array.hpp">scoped_array.hpp</a>.</li>
<li>Header <a href="../../boost/shared_ptr.hpp">shared_ptr.hpp</a>.</li>
<li>Header <a href="../../boost/shared_array.hpp">shared_array.hpp</a>.</li>
<li>Header <a href="../../boost/weak_ptr.hpp">weak_ptr.hpp</a>.</li>
<li>Test program <a href="smart_ptr_test.cpp">smart_ptr_test.cpp</a>.</li> <li>Test program <a href="smart_ptr_test.cpp">smart_ptr_test.cpp</a>.</li>
<li>Submitted by <a href="../../people/greg_colvin.htm">Greg Colvin</a> and <a href="../../people/beman_dawes.html">Beman <li>Originally submitted by
Dawes</a>.</li> <a href="../../people/greg_colvin.htm">Greg Colvin</a> and
<a href="../../people/beman_dawes.html">Beman Dawes</a>,
currently maintained by
<a href="../../people/peter_dimov.htm">Peter Dimov</a> and
<a href="../../people/darin_adler.htm">Darin Adler</a>.</li>
</ul> </ul>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->14 Mar 2001<!--webbot bot="Timestamp" endspan i-checksum="14885" -->
</p> <p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="14885" -->.</p>
</body> </body>

View File

@ -1,101 +1,144 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>scoped_array</title> <title>scoped_array</title>
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
</head> </head>
<body bgcolor="#FFFFFF" text="#000000"> <body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Class <h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86"><a name="scoped_array">scoped_array</a> class template</h1>
<a name="scoped_array">scoped_array</a></h1>
<p>Class <strong>scoped_array</strong> stores a pointer to a dynamically <p>The <b>scoped_array</b> class template stores a pointer to a dynamically allocated
allocated array. (Dynamically allocated arrays are allocated with the C++ <tt>new[]</tt> array. (Dynamically allocated arrays are allocated with the C++ <b>new[]</b>
expression.)&nbsp;&nbsp; The array pointed to is guaranteed to be deleted, expression.) The array pointed to is guaranteed to be deleted,
either on destruction of the <strong>scoped_array</strong>, or via an explicit <strong>scoped_array::reset()</strong>.</p> either on destruction of the <b>scoped_array</b>, or via an explicit <b>reset</b>.</p>
<p>Class<strong> scoped_array</strong> is a simple solution for simple
needs.&nbsp;It supplies a basic &quot;resource acquisition is <p>The <b>scoped_array</b> template is a simple solution for simple
needs. It supplies a basic &quot;resource acquisition is
initialization&quot; facility, without shared-ownership or transfer-of-ownership initialization&quot; facility, without shared-ownership or transfer-of-ownership
semantics.&nbsp; Both its name and enforcement of semantics (by being <a href="../utility/utility.htm#class noncopyable">noncopyable</a>) semantics. Both its name and enforcement of semantics (by being
signal its intent to retain ownership solely within the current scope.&nbsp; By <a href="../utility/utility.htm#class noncopyable">noncopyable</a>)
being <a href="../utility/utility.htm#class noncopyable">noncopyable</a>, it is signal its intent to retain ownership solely within the current scope.
Because it is <a href="../utility/utility.htm#class noncopyable">noncopyable</a>, it is
safer than <b>shared_array</b> for pointers which should not be copied.</p> safer than <b>shared_array</b> for pointers which should not be copied.</p>
<p>Because <strong>scoped_array</strong> is so simple, in its usual
implementation every operation is as fast as a built-in array pointer and it has no <p>Because <b>scoped_array</b> 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.</p> more space overhead that a built-in array pointer.</p>
<p>It cannot be used in C++ Standard Library containers.&nbsp; See <a href="shared_array.htm"><strong>shared_array</strong></a>
if <strong>scoped_array</strong> does not meet your needs.</p> <p>It cannot be used in C++ standard library containers.
<p>Class<strong> scoped_array</strong> cannot correctly hold a pointer to a See <a href="shared_array.htm"><b>shared_array</b></a>
single object.&nbsp; See <a href="scoped_ptr.htm"><strong>scoped_ptr</strong></a> if <b>scoped_array</b> does not meet your needs.</p>
<p>It cannot correctly hold a pointer to a single object.
See <a href="scoped_ptr.htm"><b>scoped_ptr</b></a>
for that usage.</p> for that usage.</p>
<p>A C++ Standard Library <strong>vector</strong> is a <strong> </strong>heavier duty alternative to a <strong>scoped_array</strong>.</p>
<p>The class is a template parameterized on <tt>T</tt>, the type of the object
pointed to.&nbsp;&nbsp; <tt>T</tt> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">common
requirements</a>.</p>
<h2>Class scoped_array Synopsis</h2>
<pre>#include &lt;<a href="../../boost/smart_ptr.hpp">boost/smart_ptr.hpp</a>&gt;
namespace boost {
template&lt;typename T&gt; class scoped_array : <a href="../utility/utility.htm#noncopyable">noncopyable</a> { <p>A <b>std::vector</b> is an alternative to a <b>scoped_array</b> that is
a bit heavier duty but far more flexible.
A <b>boost::array</b> is an alternative that does not use dynamic allocation.</p>
public: <p>The class template is parameterized on <b>T</b>, the type of the object
typedef T <a href="#scoped_array_element_type">element_type</a>; pointed to. <b>T</b> must meet the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
explicit <a href="#scoped_array_ctor">scoped_array</a>( T* p=0 ); // never throws <h2>Synopsis</h2>
<strong> </strong><a href="#scoped_array_~scoped_array">~scoped_array</a>();
void <a href="#scoped_array_reset">reset</a>( T* p=0 ); <pre>namespace boost {
template&lt;typename T&gt; class scoped_array : <a href="../utility/utility.htm#noncopyable">noncopyable</a> {
public:
typedef T <a href="#element_type">element_type</a>;
explicit <a href="#ctor">scoped_array</a>(T * p = 0); // never throws
<a href="#~scoped_array">~scoped_array</a>(); // never throws
void <a href="#reset">reset</a>(T * p = 0); // never throws
T &amp; <a href="#operator[]">operator[]</a>(std::size_t i) const; // never throws
T * <a href="#get">get</a>() const; // never throws
void <a href="#swap">swap</a>(scoped_array &amp; b); // never throws
};
template&lt;typename T&gt; void <a href="#free-swap">swap</a>(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws
T&amp; <a href="#scoped_array_operator[]">operator[]</a>(std::size_t i) const; // never throws
T* <a href="#scoped_array_get">get</a>() const; // never throws
};
}</pre> }</pre>
<h2>Class scoped_array Members</h2>
<h3>scoped_array <a name="scoped_array_element_type">element_type</a></h3> <h2>Members</h2>
<h3>
<a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p> <p>Provides the type of the stored pointer.</p>
<h3><a name="scoped_array_ctor">scoped_array constructors</a></h3>
<pre>explicit scoped_array( T* p=0 ); // never throws</pre> <h3><a name="ctor">constructors</a></h3>
<p>Constructs a <tt>scoped_array</tt>, storing a copy of <tt>p</tt>, which must <pre>explicit scoped_array(T * p = 0); // never throws</pre>
have been allocated via a C++ <tt>new</tt>[] expression or be 0.</p> <p>Constructs a <b>scoped_array</b>, storing a copy of <b>p</b>, which must
<p><b>T</b> is not required be a complete type.&nbsp; have been allocated via a C++ <b>new</b>[] expression or be 0.
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> <b>T</b> is not required be a complete type.
<h3><a name="scoped_array_~scoped_array">scoped_array destructor</a></h3> See the smart pointer
<pre>~scoped_array();</pre> <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Deletes the array pointed to by the stored pointer.&nbsp; Note that in C++ <tt>delete</tt>[]
on a pointer with a value of 0 is harmless.</p> <h3><a name="~scoped_array">destructor</a></h3>
<p>Does not throw exceptions.</p> <pre>~scoped_array(); // never throws</pre>
<h3>scoped_array <a name="scoped_array_reset">reset</a></h3> <p>Deletes the array pointed to by the stored pointer.
<pre>void reset( T* p=0 )();</pre> Note that <b>delete[]</b> 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 <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="reset">reset</a></h3>
<pre>void reset(T * p = 0); // never throws</pre>
<p>If p is not equal to the stored pointer, deletes the array pointed to by the <p>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 stored pointer and then stores a copy of p, which must have been allocated via a
C++ <tt>new[]</tt> expression or be 0.</p> C++ <b>new[]</b> expression or be 0.
<p>Does not throw exceptions.</p> The guarantee that this does not throw exceptions depends on the requirement that the
<h3>scoped_array <a name="scoped_array_operator[]">operator[]</a></h3> deleted array's objects' destructors do not throw exceptions.
<p><tt>T&amp; operator[](std::size_t i) const; // never throws</tt></p> See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Returns a reference to element <tt>i</tt> of the array pointed to by the
stored pointer.</p> <h3><a name="operator[]">subscripting</a></h3>
<p>Behavior is undefined (and almost certainly undesirable) if <tt>get()==0</tt>, <pre>T &amp; operator[](std::size_t i) const; // never throws</pre>
or if <tt>i</tt> is less than 0 or is greater or equal to the number of elements <p>Returns a reference to element <b>i</b> of the array pointed to by the
stored pointer.
Behavior is undefined and almost certainly undesirable if the stored pointer is 0,
or if <b>i</b> is less than 0 or is greater than or equal to the number of elements
in the array.</p> in the array.</p>
<h3>scoped_array <a name="scoped_array_get">get</a></h3>
<pre>T* get() const; // never throws</pre> <h3><a name="get">get</a></h3>
<p><b>T</b> is not required be a complete type.&nbsp; <pre>T * get() const; // never throws</pre>
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> <p>Returns the stored pointer.
<p>Returns the stored pointer.</p> <b>T</b> need not be a complete type.
<h2>Class <a name="shared_array_example">scoped_array example</a></h2> See the smart pointer
<p>[To be supplied. In the meantime, see <a href="smart_ptr_test.cpp">smart_ptr_test.cpp</a>.]</p> <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="swap">swap</a></h3>
<pre>void swap(scoped_array &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2>
<h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt; void swap(scoped_array&lt;T&gt; &amp; a, scoped_array&lt;T&gt; &amp; b); // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p>
<hr> <hr>
<p>Revised&nbsp; <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan
-->24 May, 2001<!--webbot bot="Timestamp" endspan i-checksum="13964" <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan-->1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="13964"--></p>
-->
</p> <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
<p><EFBFBD> Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use, Permission to copy, use, modify, sell and distribute this document is granted
modify, sell and distribute this document is granted provided this copyright provided this copyright notice appears in all copies.
notice appears in all copies. This document is provided &quot;as is&quot; This document is provided &quot;as is&quot; without express or implied warranty,
without express or implied warranty, and with no claim as to its suitability for and with no claim as to its suitability for any purpose.</p>
any purpose.</p>
</body> </body>

View File

@ -1,152 +1,216 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>scoped_ptr</title> <title>scoped_ptr</title>
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
</head> </head>
<body bgcolor="#FFFFFF" text="#000000"> <body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Class <h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86"><a name="scoped_ptr">scoped_ptr</a> class template</h1>
<a name="scoped_ptr">scoped_ptr</a></h1>
<p>Class <strong>scoped_ptr</strong> stores a pointer to a dynamically allocated <p>The <b>scoped_ptr</b> class template stores a pointer to a dynamically allocated
object. (Dynamically allocated objects are allocated with the C++ <tt>new</tt> object. (Dynamically allocated objects are allocated with the C++ <b>new</b>
expression.)&nbsp;&nbsp; The object pointed to is guaranteed to be deleted, expression.) The object pointed to is guaranteed to be deleted,
either on destruction of the <strong>scoped_ptr</strong>, or via an explicit <strong>scoped_ptr::reset()</strong>.&nbsp; either on destruction of the <b>scoped_ptr</b>, or via an explicit <b>reset</b>.
See <a href="#scoped_ptr_example">example</a>.</p> See the <a href="#example">example</a>.</p>
<p>Class<strong> scoped_ptr</strong> is a simple solution for simple
needs.&nbsp; It supplies a basic &quot;resource acquisition is <p>The <b>scoped_ptr</b> template is a simple solution for simple
needs. It supplies a basic &quot;resource acquisition is
initialization&quot; facility, without shared-ownership or transfer-of-ownership initialization&quot; facility, without shared-ownership or transfer-of-ownership
semantics.&nbsp; Both its name and enforcement of semantics (by being <a href="../utility/utility.htm#class noncopyable">noncopyable</a>) semantics. Both its name and enforcement of semantics (by being
signal its intent to retain ownership solely within the current scope.&nbsp; <a href="../utility/utility.htm#class noncopyable">noncopyable</a>)
signal its intent to retain ownership solely within the current scope.
Because it is <a href="../utility/utility.htm#class noncopyable">noncopyable</a>, it is Because it is <a href="../utility/utility.htm#class noncopyable">noncopyable</a>, it is
safer than <b>shared_ptr</b> or <b> std::auto_ptr</b> for pointers which should not be safer than <b>shared_ptr</b> or <b>std::auto_ptr</b> for pointers which should not be
copied.</p> copied.</p>
<p>Because <strong>scoped_ptr</strong> is so simple, in its usual implementation
<p>Because <b>scoped_ptr</b> is simple, in its usual implementation
every operation is as fast as for a built-in pointer and it has no more space overhead every operation is as fast as for a built-in pointer and it has no more space overhead
that a built-in pointer.&nbsp; (Because of the &quot;complete type&quot; that a built-in pointer.</p>
requirement for delete and reset members, they may have one additional function
call overhead in certain idioms.&nbsp; See <a href="#Handle/Body">Handle/Body <p>It cannot be used in C++ Standard Library containers.
Idiom</a>.)&nbsp;&nbsp;&nbsp;</p> See <a href="shared_ptr.htm"><b>shared_ptr</b></a>
<p>Class<strong> scoped_ptr</strong> cannot be used in C++ Standard Library containers.&nbsp; See <a href="shared_ptr.htm"><strong>shared_ptr</strong></a> or <b>std::auto_ptr</b> if <b>scoped_ptr</b> does not meet your needs.</p>
or std::auto_ptr if <strong>scoped_ptr</strong> does not meet your needs.</p>
<p>Class<strong> scoped_ptr</strong> cannot correctly hold a pointer to a <p>It cannot correctly hold a pointer to a
dynamically allocated array.&nbsp; See <a href="scoped_array.htm"><strong>scoped_array</strong></a> dynamically allocated array. See <a href="scoped_array.htm"><b>scoped_array</b></a>
for that usage.</p> for that usage.</p>
<p>The class is a template parameterized on <tt>T</tt>, the type of the object
pointed to.&nbsp;&nbsp; <tt>T</tt> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">common
requirements</a>.</p>
<h2>Class scoped_ptr Synopsis</h2>
<pre>#include &lt;<a href="../../boost/smart_ptr.hpp">boost/smart_ptr.hpp</a>&gt;
namespace boost {
template&lt;typename T&gt; class scoped_ptr : <a href="../utility/utility.htm#class noncopyable">noncopyable</a> { <p>The class template is parameterized on <b>T</b>, the type of the object
pointed to. <b>T</b> must meet the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
public: <h2>Synopsis</h2>
typedef T <a href="#scoped_ptr_element_type">element_type</a>;
explicit <a href="#scoped_ptr_ctor">scoped_ptr</a>( T* p=0 ); // never throws <pre>namespace boost {
<strong> </strong><a href="#scoped_ptr_~scoped_ptr">~scoped_ptr</a>();
void <a href="#scoped_ptr_reset">reset</a>( T* p=0 ); template&lt;typename T&gt; class scoped_ptr : <a href="../utility/utility.htm#class noncopyable">noncopyable</a> {
public:
typedef T <a href="#element_type">element_type</a>;
explicit <a href="#constructors">scoped_ptr</a>(T * p = 0); // never throws
<a href="#~scoped_ptr">~scoped_ptr</a>(); // never throws
void <a href="#reset">reset</a>(T * p = 0); // never throws
T &amp; <a href="#indirection">operator*</a>() const; // never throws
T * <a href="#indirection">operator-&gt;</a>() const; // never throws
T * <a href="#get">get</a>() const; // never throws
void <a href="#swap">swap</a>(scoped_ptr &amp; b); // never throws
};
template&lt;typename T&gt; void <a href="#free-swap">swap</a>(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws
T&amp; <a href="#scoped_ptr_operator*">operator*</a>() const; // never throws
T* <a href="#scoped_ptr_operator-&gt;">operator-&gt;</a>() const; // never throws
T* <a href="#scoped_ptr_get">get</a>() const; // never throws
};
}</pre> }</pre>
<h2>Class scoped_ptr Members</h2>
<h3>scoped_ptr <a name="scoped_ptr_element_type">element_type</a></h3> <h2>Members</h2>
<h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p> <p>Provides the type of the stored pointer.</p>
<h3><a name="scoped_ptr_ctor">scoped_ptr constructors</a></h3>
<pre>explicit scoped_ptr( T* p=0 ); // never throws</pre> <h3><a name="constructors">constructors</a></h3>
<p><b>T</b> is not required be a complete type.&nbsp; <pre>explicit scoped_ptr(T * p = 0); // never throws</pre>
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> <p>Constructs a <b>scoped_ptr</b>, storing a copy of <b>p</b>, which must
<p>Constructs a <tt>scoped_ptr</tt>, storing a copy of <tt>p</tt>, which must have been allocated via a C++ <b>new</b> expression or be 0.
have been allocated via a C++ <tt>new</tt> expression or be 0.</p> <b>T</b> is not required be a complete type.
<h3><a name="scoped_ptr_~scoped_ptr">scoped_ptr destructor</a></h3> See the smart pointer
<pre>~scoped_ptr();</pre> <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Deletes the object pointed to by the stored pointer.&nbsp; Note that in C++, <tt>delete</tt>
on a pointer with a value of 0 is harmless.</p> <h3><a name="~scoped_ptr">destructor</a></h3>
<p>Does not throw exceptions.</p> <pre>~scoped_ptr(); // never throws</pre>
<h3>scoped_ptr <a name="scoped_ptr_reset">reset</a></h3> <p>Deletes the object pointed to by the stored pointer.
<pre>void reset( T* p=0 );</pre> Note that <b>delete</b> 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 <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="reset">reset</a></h3>
<pre>void reset(T * p = 0); // never throws</pre>
<p>If p is not equal to the stored pointer, deletes the object pointed to by the <p>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 stored pointer and then stores a copy of p, which must have been allocated via a
C++ <tt>new</tt> expression or be 0.</p> C++ <b>new</b> expression or be 0.
<p>Does not throw exceptions.</p> The guarantee that this does not throw exceptions depends on the requirement that the
<h3>scoped_ptr <a name="scoped_ptr_operator*">operator*</a></h3> deleted object's destructor does not throw exceptions.
<pre>T&amp; operator*() const; // never throws</pre> See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Returns a reference to the object pointed to by the stored pointer.</p>
<h3>scoped_ptr <a name="scoped_ptr_operator-&gt;">operator-&gt;</a> and <a name="scoped_ptr_get">get</a></h3>
<pre>T* operator-&gt;() const; // never throws
T* get() const; // never throws</pre>
<p><b>T</b> is not required by get() be a complete type.&nbsp; See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
<p>Both return the stored pointer.</p>
<h2>Class <a name="scoped_ptr_example">scoped_ptr example</a>s</h2>
<pre>#include &lt;iostream&gt;
#include &lt;boost/smart_ptr.h&gt;
struct Shoe { ~Shoe(){ std::cout &lt;&lt; &quot;Buckle my shoe&quot; &lt;&lt; std::endl; } }; <h3><a name="indirection">indirection</a></h3>
<pre>T &amp; operator*() const; // never throws</pre>
<p>Returns a reference to the object pointed to by the stored pointer.
Behavior is undefined if the stored pointer is 0.</p>
<pre>T * operator-&gt;() const; // never throws</pre>
<p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p>
<h3><a name="get">get</a></h3>
<pre>T * get() const; // never throws</pre>
<p>Returns the stored pointer.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="swap">swap</a></h3>
<pre>void swap(scoped_ptr &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2>
<h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt; void swap(scoped_ptr&lt;T&gt; &amp; a, scoped_ptr&lt;T&gt; &amp; b); // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p>
<h2><a name="example">Example</a></h2>
<p>Here's an example that uses <b>scoped_ptr</b>.</p>
<blockquote>
<pre>#include &lt;boost/scoped_ptr.hpp&gt;
#include &lt;iostream&gt;
struct Shoe { ~Shoe() { std::cout &lt;&lt; &quot;Buckle my shoe\n&quot;; } };
class MyClass { class MyClass {
boost::scoped_ptr&lt;int&gt; ptr; boost::scoped_ptr&lt;int&gt; ptr;
public: public:
MyClass() : ptr(new int) { *ptr = 0; } MyClass() : ptr(new int) { *ptr = 0; }
int add_one() { return ++*ptr; } int add_one() { return ++*ptr; }
}; };
void main() { void main()
{
boost::scoped_ptr&lt;Shoe&gt; x(new Shoe); boost::scoped_ptr&lt;Shoe&gt; x(new Shoe);
MyClass my_instance; MyClass my_instance;
std::cout &lt;&lt; my_instance.add_one() &lt;&lt; std::endl; std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n';
std::cout &lt;&lt; my_instance.add_one() &lt;&lt; std::endl; std::cout &lt;&lt; my_instance.add_one() &lt;&lt; '\n';
}</pre> }</pre>
<p>The example program produces the beginning of a child's nursery rhyme as </blockquote>
output:</p>
<p>The example program produces the beginning of a child's nursery rhyme:</p>
<blockquote> <blockquote>
<pre>1 <pre>1
2 2
Buckle my shoe</pre> Buckle my shoe</pre>
</blockquote> </blockquote>
<h2>Rationale</h2> <h2>Rationale</h2>
<p>The primary reason to use <b> scoped_ptr</b> rather than <b> auto_ptr</b> 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 <p>The primary reason to use <b>scoped_ptr</b> rather than <b>auto_ptr</b> is to let readers
ownership.</p> of your code know that you intend "resource acquisition is initialization" to be applied only
<p>A secondary reason to use <b> scoped_ptr</b> is to prevent a later maintenance programmer from adding a function that actually transfers for the current scope, and have no intent to transfer ownership.</p>
ownership by returning the <b> auto_ptr</b> (because the maintenance programmer saw
<b>auto_ptr</b>, and assumed ownership could safely be transferred.)&nbsp;</p> <p>A secondary reason to use <b>scoped_ptr</b> is to prevent a later maintenance programmer
<p>Think of <b>bool</b> vs <b>int</b>. We all know that under the covers <b> bool</b> is usually from adding a function that transfers ownership by returning the <b>auto_ptr</b>,
just an <b>int</b>. Indeed, some argued against including <b> bool</b> in the because the maintenance programmer saw <b>auto_ptr</b>, and assumed ownership could safely
C++ standard because of that. But by coding <b> bool</b> rather than <b> int</b>, you tell your readers be transferred.</p>
what your intent is. Same with <b> scoped_ptr</b> - you are signaling intent.</p>
<p>It has been suggested that <b>boost::scoped_ptr&lt;T&gt;</b> is equivalent to <p>Think of <b>bool</b> vs <b>int</b>. We all know that under the covers <b>bool</b> is usually
<b>std::auto_ptr&lt;T> const</b>.&nbsp; Ed Brey pointed out, however, that just an <b>int</b>. Indeed, some argued against including <b>bool</b> in the
reset() will not work on a <b>std::auto_ptr&lt;T> const.</b></p> C++ standard because of that. But by coding <b>bool</b> rather than <b>int</b>, you tell your readers
what your intent is. Same with <b>scoped_ptr</b>; by using it you are signaling intent.</p>
<p>It has been suggested that <b>scoped_ptr&lt;T&gt;</b> is equivalent to
<b>std::auto_ptr&lt;T> const</b>. Ed Brey pointed out, however, that
<b>reset</b> will not work on a <b>std::auto_ptr&lt;T> const.</b></p>
<h2><a name="Handle/Body">Handle/Body</a> Idiom</h2> <h2><a name="Handle/Body">Handle/Body</a> Idiom</h2>
<p>One common usage of <b>scoped_ptr</b> is to implement a handle/body (also <p>One common usage of <b>scoped_ptr</b> is to implement a handle/body (also
called pimpl) idiom which avoids exposing the body (implementation) in the header called pimpl) idiom which avoids exposing the body (implementation) in the header
file.</p> file.</p>
<p>The <a href="scoped_ptr_example_test.cpp">scoped_ptr_example_test.cpp</a> <p>The <a href="scoped_ptr_example_test.cpp">scoped_ptr_example_test.cpp</a>
sample program includes a header file, <a href="scoped_ptr_example.hpp">scoped_ptr_example.hpp</a>, sample program includes a header file, <a href="scoped_ptr_example.hpp">scoped_ptr_example.hpp</a>,
which uses a <b>scoped_ptr&lt;&gt;</b> to an incomplete type to hide the which uses a <b>scoped_ptr&lt;&gt;</b> to an incomplete type to hide the
implementation.&nbsp;&nbsp; The implementation. The
instantiation of member functions which require a complete type occurs in the <a href="scoped_ptr_example.cpp">scoped_ptr_example.cpp</a> instantiation of member functions which require a complete type occurs in
the <a href="scoped_ptr_example.cpp">scoped_ptr_example.cpp</a>
implementation file.</p> implementation file.</p>
<h2>FAQ</h2>
<h2>Frequently Asked Questions</h2>
<p><b>Q</b>. Why doesn't <b>scoped_ptr</b> have a release() member?<br> <p><b>Q</b>. Why doesn't <b>scoped_ptr</b> have a release() member?<br>
<b>A</b>. Because the whole point of <b>scoped_ptr</b> is to signal intent not <b>A</b>. Because the point of <b>scoped_ptr</b> is to signal intent, not
to transfer ownership.&nbsp; Use <b>std::auto_ptr</b> if ownership transfer is to transfer ownership. Use <b>std::auto_ptr</b> if ownership transfer is
required.</p> required.</p>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->24 May 2001<!--webbot bot="Timestamp" endspan i-checksum="15110" --></p>
<p><EFBFBD> Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use, <p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="15110" --></p>
modify, sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided &quot;as is&quot; <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
without express or implied warranty, and with no claim as to its suitability for Permission to copy, use, modify, sell and distribute this document is granted
any purpose.</p> provided this copyright notice appears in all copies.
This document is provided &quot;as is&quot; without express or implied warranty,
and with no claim as to its suitability for any purpose.</p>
</body> </body>

View File

@ -1,6 +1,6 @@
// Boost scoped_ptr_example header file ------------------------------------// // Boost scoped_ptr_example header file ------------------------------------//
#include <boost/smart_ptr.hpp> #include <boost/scoped_ptr.hpp>
// The point of this example is to prove that even though // The point of this example is to prove that even though
// example::implementation is an incomplete type in translation units using // example::implementation is an incomplete type in translation units using

View File

@ -1,188 +1,223 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>shared_array</title> <title>shared_array</title>
<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
</head> </head>
<body bgcolor="#FFFFFF" text="#000000"> <body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Class <h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">shared_array class template</h1>
<a name="shared_array">shared_array</a></h1>
<p>Class <strong>shared_array</strong> stores a pointer to a dynamically <p>The <b>shared_array</b> class template stores a pointer to a dynamically allocated
allocated array. (Dynamically allocated arrays are allocated with the C++ <tt>new[]</tt> array. (Dynamically allocated array are allocated with the C++ <b>new[]</b>
expression.)&nbsp;&nbsp; The array pointed to is guaranteed to be deleted, expression.) The object pointed to is guaranteed to be deleted when
either on destruction of the <strong>shared_array</strong>, on <strong>shared_array::operator=()</strong>, the last <b>shared_array</b> pointing to it is destroyed or reset.</p>
or via an explicit <strong>shared_array::reset()</strong>.&nbsp; See <a href="#shared_array_example">example</a>.</p>
<p>Class<strong> shared_array</strong> meets the <strong>CopyConstuctible</strong> <p>Every <b>shared_array</b> meets the <b>CopyConstructible</b>
and <strong>Assignable</strong> requirements of the C++ Standard Library, and so and <b>Assignable</b> requirements of the C++ Standard Library, and so
can be used in C++ Standard Library containers.&nbsp; A specialization of std:: can be used in standard library containers. Comparison operators
less&lt; &gt; for&nbsp; boost::shared_ptr&lt;Y&gt; is supplied so that&nbsp;<strong> are supplied so that <b>shared_array</b> works with
shared_array</strong> works by default for Standard Library's Associative the standard library's associative containers.</p>
Container Compare template parameter.&nbsp; For compilers not supporting partial
specialization, the user must explicitly pass the less&lt;&gt; functor.</p> <p>Normally, a <b>shared_array</b> cannot correctly hold a pointer to a
<p>Class<strong> shared_array</strong> cannot correctly hold a pointer to a dynamically allocated array. See <a href="shared_ptr.htm"><b>shared_ptr</b></a>
single object.&nbsp; See <a href="shared_ptr.htm"><strong>shared_ptr</strong></a>
for that usage.</p> for that usage.</p>
<p>Class<strong> shared_array</strong> will not work correctly with cyclic data
structures. For example, if main() holds a shared_array pointing to array A,
which directly or indirectly holds a shared_array pointing back to array A, then
array A's use_count() will be 2, and destruction of the main() shared_array will
leave array A dangling with a use_count() of 1.</p>
<p>A C++ Standard Library <strong>vector</strong> is <strong> </strong>a <strong>
</strong>heavier duty alternative to a <strong>shared_array</strong>.</p>
<p>The class is a template parameterized on <tt>T</tt>, the type of the object
pointed to.&nbsp;&nbsp; <tt>T</tt> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">Common
requirements</a>.</p>
<h2>Class shared_array Synopsis</h2>
<pre>#include &lt;<a href="../../boost/smart_ptr.hpp">boost/smart_ptr.hpp</a>&gt;
namespace boost {
template&lt;typename T&gt; class shared_array { <p>Because the implementation uses reference counting, <b>shared_array</b> will not work
correctly with cyclic data structures. For example, if <b>main()</b> holds a <b>shared_array</b>
to <b>A</b>, which directly or indirectly holds a <b>shared_array</b> back to <b>A</b>,
<b>A</b>'s use count will be 2. Destruction of the original <b>shared_array</b>
will leave <b>A</b> dangling with a use count of 1.</p>
public: <p>A <b>shared_ptr</b> to a <b>std::vector</b> is an alternative to a <b>shared_array</b> that is
typedef T <a href="#shared_array_element_type">element_type</a>; a bit heavier duty but far more flexible.</p>
explicit <a href="#shared_array_ctor">shared_array</a>( T* p=0 ); <p>The class template is parameterized on <b>T</b>, the type of the object
<a href="#shared_array_ctor">shared_array</a>( const shared_array&amp; ); // never throws pointed to. <b>T</b> must meet the smart pointer
<strong> </strong><a href="#shared_array_~shared_array">~shared_array</a>(); <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
shared_array&amp; <a href="#shared_array_operator=">operator=</a>( const shared_array&amp; ); // never throws <h2>Synopsis</h2>
void <a href="#shared_array_reset">reset</a>( T* p=0 ); <pre>namespace boost {
T&amp; <a href="#shared_array_operator[]">operator[]</a>(std::size_t i) const; // never throws template&lt;typename T&gt; class shared_array {
T* <a href="#shared_array_get">get</a>() const; // never throws
long <a href="#shared_array_use_count">use_count</a>() const; // never throws public:
bool <a href="#shared_array_unique">unique</a>() const; // never throws typedef T <a href="#element_type">element_type</a>;
void <a href="#shared_array_swap">swap</a>( shared_array&lt;T&gt;&amp; other ) throw() explicit <a href="#constructors">shared_array</a>(T * p = 0);
}; template&lt;typename D&gt; <a href="#constructors">shared_array</a>(T * p, D d);
<a href="#destructor">~shared_array</a>(); // never throws
template&lt;typename T&gt; <a href="#constructors">shared_array</a>(shared_array const &amp; r); // never throws
inline bool operator==(const shared_array&lt;T&gt;&amp; a, const shared_array&lt;T&gt;&amp; b)
{ return a.get() == b.get(); }
template&lt;typename T&gt; shared_array &amp; <a href="#assignment">operator=</a>(shared_array const &amp; r); // never throws
inline bool operator!=(const shared_array&lt;T&gt;&amp; a, const shared_array&lt;T&gt;&amp; b)
{ return a.get() != b.get(); }
}</pre>
<pre>namespace std {
template&lt;typename T&gt; void <a href="#reset">reset</a>(T * p = 0); // never throws
inline void swap(boost::shared_array&lt;T&gt;&amp; a, boost::shared_array&lt;T&gt;&amp; b) template&lt;typename D&gt; void <a href="#reset">reset</a>(T * p, D d); // never throws
{ a.swap(b); }
template&lt;typename T&gt; T &amp; <a href="#indexing">operator[]</a>(std::ptrdiff_t i) const() const; // never throws
struct less&lt; boost::shared_array&lt;T&gt; &gt; T * <a href="#get">get</a>() const; // never throws
: binary_function&lt;boost::shared_array&lt;T&gt;, boost::shared_array&lt;T&gt;, bool&gt;
{ bool <a href="#unique">unique</a>() const; // never throws
bool operator()(const boost::shared_array&lt;T&gt;&amp; a, long <a href="#use_count">use_count</a>() const; // never throws
const boost::shared_array&lt;T&gt;&amp; b) const
{ return less&lt;T*&gt;()(a.get(),b.get()); } void <a href="#swap">swap</a>(shared_array&lt;T&gt; &amp; b); // never throws
}; };
} // namespace std </pre> template&lt;typename T&gt;
<p>Specialization of std::swap uses the fast, non-throwing swap that's provided bool <a href="#operator==">operator==</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
as a member function instead of using the default algorithm which creates a template&lt;typename T&gt;
temporary and uses assignment.<br> bool <a href="#operator!=">operator!=</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
<br> template&lt;typename T&gt;
Specialization of std::less allows use of shared arrays as keys in&nbsp;C++ bool <a href="#operator&lt;">operator&lt;</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
Standard Library associative collections.<br>
<br> template&lt;typename T&gt; void <a href="#free-swap">swap</a>(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b); // never throws
The std::less specializations use std::less&lt;T*&gt; to perform the
comparison.&nbsp; This insures that pointers are handled correctly, since the }</pre>
standard mandates that relational operations on pointers are unspecified (5.9 [expr.rel]
paragraph 2) but std::less&lt;&gt; on pointers is well-defined (20.3.3 [lib.comparisons] <h2>Members</h2>
paragraph 8).<br>
<br> <h3><a name="element_type">element_type</a></h3>
It's still a controversial question whether supplying only std::less is better
than supplying a full range of comparison operators (&lt;, &gt;, &lt;=, &gt;=).</p>
<p>The current implementation does not supply the specializations if the macro
name BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION is defined.</p>
<h2>Class shared_array Members</h2>
<h3>shared_array <a name="shared_array_element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p> <p>Provides the type of the stored pointer.</p>
<h3><a name="shared_array_ctor">shared_array constructors</a></h3>
<pre>explicit shared_array( T* p=0 );</pre> <h3><a name="constructors">constructors</a></h3>
<p>Constructs a <strong>shared_array</strong>, storing a copy of <tt>p</tt>,
which must have been allocated via a C++ <tt>new</tt>[] expression or be 0. <pre>explicit shared_array(T * p = 0);</pre>
Afterwards, use_count() is 1 (even if p==0; see <a href="#shared_array_~shared_array">~shared_array</a>).</p> <p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b>, which
<p>The only exception which may be thrown is <tt>std::bad_alloc</tt>.&nbsp; If must be a pointer to an array that was allocated via a C++ <b>new[]</b> expression or be 0.
an exception is thrown,&nbsp; <tt>delete[] p</tt> is called.</p> Afterwards, the <a href="#use_count">use count</a> is 1 (even if p == 0; see <a href="#destructor">~shared_array</a>).
<pre>shared_array( const shared_array&amp; r); // never throws</pre> The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
<p>Constructs a <strong>shared_array</strong>, as if by storing a copy of the If an exception is thrown, <b>delete[] p</b> is called.</p>
pointer stored in <strong>r</strong>. Afterwards, <strong>use_count()</strong>
for all copies is 1 more than the initial <strong>r.use_count()</strong>.</p> <pre>template&lt;typename D&gt; shared_array(T * p, D d);</pre>
<h3><a name="shared_array_~shared_array">shared_array destructor</a></h3> <p>Constructs a <b>shared_array</b>, storing a copy of <b>p</b> and of <b>d</b>.
<pre>~shared_array();</pre> Afterwards, the <a href="#use_count">use count</a> is 1.
<p>If <strong>use_count()</strong> == 1, deletes the array pointed to by the <b>D</b>'s copy constructor must not throw.
stored pointer.&nbsp;Otherwise, <strong>use_count()</strong> for any remaining When the the time comes to delete the array pointed to by <b>p</b>, the object
copies is decremented by 1. Note that in C++ <tt>delete</tt>[] on a pointer with <b>d</b> is used in the statement <b>d(p)</b>. Invoking the object <b>d</b> with
a value of 0 is harmless.</p> parameter <b>p</b> in this way must not throw.
<p>Does not throw exceptions.</p> The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
<h3>shared_array <a name="shared_array_operator=">operator=</a></h3> If an exception is thrown, <b>d(p)</b> is called.</p>
<pre>shared_array&amp; operator=( const shared_array&amp; r); // never throws</pre>
<p>First, if <strong>use_count()</strong> == 1, deletes the array pointed to by <pre>shared_array(shared_array const &amp; r); // never throws</pre>
the stored pointer.&nbsp;Otherwise, <strong>use_count()</strong> for any <p>Constructs a <b>shared_array</b>, as if by storing a copy of the
remaining copies is decremented by 1. Note that in C++ <tt>delete</tt>[] on a pointer stored in <b>r</b>. Afterwards, the <a href="#use_count">use count</a>
pointer with a value of 0 is harmless.</p> for all copies is 1 more than the initial use count.</p>
<p>Then replaces the contents of <strong>this</strong>, as if by storing a copy
of the pointer stored in <strong>r</strong>. Afterwards, <strong>use_count()</strong> <h3><a name="destructor">destructor</a></h3>
for all copies is 1 more than the initial <strong>r.use_count()</strong>.&nbsp;</p>
<h3>shared_array <a name="shared_array_reset">reset</a></h3> <pre>~shared_array(); // never throws</pre>
<pre>void reset( T* p=0 );</pre> <p>Decrements the <a href="#use_count">use count</a>. Then, if the use count is 0,
<p>First, if <strong>use_count()</strong> == 1, deletes the array pointed to by deletes the array pointed to by the stored pointer.
the stored pointer.&nbsp;Otherwise, <strong>use_count()</strong> for any Note that <b>delete[]</b> on a pointer with a value of 0 is harmless.
remaining copies is decremented by 1. Note that in C++&nbsp; <tt>delete</tt>[] <b>T</b> need not be a complete type.
on a pointer with a value of 0 is harmless.</p> The guarantee that this does not throw exceptions depends on the requirement that the
<p>Then replaces the contents of <strong>this</strong>, as if by storing a copy deleted object's destructor does not throw exceptions.
of <strong>p</strong>, which must have been allocated via a C++ <tt>new</tt>[] See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
expression or be 0. Afterwards, <strong>use_count()</strong> is 1 (even if p==0;
see <a href="#shared_array_~shared_array">~shared_array</a>).</p> <h3><a name="operator=">assignment</a></h3>
<p>The only exception which may be thrown is <tt>std::bad_alloc</tt>.&nbsp; If
an exception is thrown,&nbsp; <tt>delete[] p</tt> is called.</p> <pre>shared_array &amp; <a href="#assignment">operator=</a>(shared_array const &amp; r); // never throws</pre>
<h3>shared_array <a name="shared_array_operator[]">operator[]</a></h3> <p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
<p><tt>T&amp; operator[](std::size_t i) const; // never throws</tt></p> then replaces this <b>shared_array</b> with the new one, destroying the replaced object.</p>
<p>Returns a reference to element <tt>i</tt> of the array pointed to by the
stored pointer.</p> <h3><a name="reset">reset</a></h3>
<p>Behavior is undefined (and almost certainly undesirable) if <tt>get()==0</tt>,
or if <tt>i</tt> is less than 0 or is greater or equal to the number of elements <pre>void reset(T * p = 0);</pre>
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
then replaces this <b>shared_array</b> with the new one, destroying the replaced object.
The only exception which may be thrown is <b>std::bad_alloc</b>. If
an exception is thrown, <b>delete[] p</b> is called.</p>
<pre>template&lt;typename D&gt; void reset(T * p, D d);</pre>
<p>Constructs a new <b>shared_array</b> as described <a href="#constructors">above</a>,
then replaces this <b>shared_array</b> with the new one, destroying the replaced object.
<b>D</b>'s copy constructor must not throw.
The only exception which may be thrown is <b>std::bad_alloc</b>. If
an exception is thrown, <b>d(p)</b> is called.</p>
<h3><a name="indirection">indexing</a></h3>
<pre>T &amp; operator[](std::size_t i) const; // never throws</pre>
<p>Returns a reference to element <b>i</b> of the array pointed to by the stored pointer.
Behavior is undefined and almost certainly undesirable if the stored pointer is 0,
or if <b>i</b> is less than 0 or is greater than or equal to the number of elements
in the array.</p> in the array.</p>
<h3>shared_array <a name="shared_array_get">get</a></h3>
<pre>T* get() const; // never throws</pre> <h3><a name="get">get</a></h3>
<p><b>T</b> is not required be a complete type.&nbsp; <pre>T * get() const; // never throws</pre>
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> <p>Returns the stored pointer.
<p>Returns the stored pointer.</p> <b>T</b> need not be a complete type.
<h3>shared_array<a name="shared_array_use_count"> use_count</a></h3> See the smart pointer
<p><tt>long use_count() const; // never throws</tt></p> <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p><b>T</b> is not required be a complete type.&nbsp;
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> <h3><a name="unique">unique</a></h3>
<p>Returns the number of <strong>shared_arrays</strong> sharing ownership of the <pre>bool unique() const; // never throws</pre>
stored pointer.</p> <p>Returns true if no other <b>shared_array</b> is sharing ownership of
<h3>shared_array <a name="shared_array_unique">unique</a></h3> the stored pointer, false otherwise.
<p><tt>bool unique() const; // never throws</tt></p> <b>T</b> need not be a complete type.
<p><b>T</b> is not required be a complete type.&nbsp; See the smart pointer
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Returns <strong>use_count()</strong> == 1.</p>
<h3><a name="shared_array_swap">shared_array swap</a></h3> <h3><a name="use_count">use_count</a></h3>
<p><code>void swap( shared_array&lt;T&gt;&amp; other ) throw()</code></p> <pre>long use_count() const; // never throws</pre>
<p><b>T</b> is not required be a complete type.&nbsp; <p>Returns the number of <b>shared_array</b> objects sharing ownership of the
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> stored pointer.
<p>Swaps the two smart pointers, as if by std::swap.</p> <b>T</b> need not be a complete type.
<h2>Class <a name="shared_array_example">shared_array example</a></h2> See the smart pointer
<p>[To be supplied. In the meantime, see <a href="smart_ptr_test.cpp">smart_ptr_test.cpp</a>.]</p> <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Because <b>use_count</b> is not necessarily efficient to implement for
implementations of <b>shared_array</b> 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.</p>
<h3><a name="swap">swap</a></h3>
<pre>void swap(shared_ptr &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2>
<h3><a name="comparison">comparison</a></h3>
<pre>template&lt;typename T&gt;
bool <a href="#operator==">operator==</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
template&lt;typename T&gt;
bool <a href="#operator!=">operator!=</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws
template&lt;typename T&gt;
bool <a href="#operator&lt;">operator&lt;</a>(shared_array&lt;T&gt; const &amp; a, shared_array&lt;T&gt; const &amp; b); // never throws</pre>
<p>Compares the stored pointers of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>The <b>operator&lt;</b> overload is provided to define an ordering so that <b>shared_array</b>
objects can be used in associative containers such as <b>std::map</b>.
The implementation uses std::less&lt;T*&gt; 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&lt;&gt; on pointers is well-defined (20.3.3 [lib.comparisons]
paragraph 8).</p>
<h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt;
void swap(shared_array&lt;T&gt; &amp; a, shared_array&lt;T&gt; &amp; b) // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->24 May, 2001<!--webbot bot="Timestamp" endspan i-checksum="13964" -->
</p> <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->1 February 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
<p><EFBFBD> Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use,
modify, sell and distribute this document is granted provided this copyright <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
notice appears in all copies. This document is provided &quot;as is&quot; Permission to copy, use, modify, sell and distribute this document is granted
without express or implied warranty, and with no claim as to its suitability for provided this copyright notice appears in all copies.
any purpose.</p> This document is provided &quot;as is&quot; without express or implied warranty,
and with no claim as to its suitability for any purpose.</p>
</body> </body>

View File

@ -1,284 +1,356 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>shared_ptr</title> <title>shared_ptr</title>
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
<meta name="ProgId" content="FrontPage.Editor.Document">
</head> </head>
<body bgcolor="#FFFFFF" text="#000000"> <body bgcolor="#FFFFFF" text="#000000">
<h1> <h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">shared_ptr class template</h1>
<img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Class
<a name="shared_ptr">shared_ptr</a></h1> <p><a href="#Introduction">Introduction</a><br>
<p><a href="#Introduction">Introduction<br> <a href="#Synopsis">Synopsis</a><br>
Synopsis</a><br>
<a href="#Members">Members</a><br> <a href="#Members">Members</a><br>
<a href="#shared_ptr_example">Example</a><br> <a href="#functions">Free Functions</a><br>
<a href="#example">Example</a><br>
<a href="#Handle/Body">Handle/Body Idiom</a><br> <a href="#Handle/Body">Handle/Body Idiom</a><br>
<a href="#FAQ">Frequently Asked Questions</a><br> <a href="#FAQ">Frequently Asked Questions</a><br>
<a href="smarttests.htm">Smart Pointer Timings</a></p> <a href="smarttests.htm">Smart Pointer Timings</a></p>
<h2><a name="Introduction">Introduction</a></h2> <h2><a name="Introduction">Introduction</a></h2>
<p>Class <strong>shared_ptr</strong> stores a pointer to a dynamically allocated
object. (Dynamically allocated objects are allocated with the C++ <tt>new</tt> <p>The <b>shared_ptr</b> class template stores a pointer to a dynamically allocated
expression.)&nbsp;&nbsp; The object pointed to is guaranteed to be deleted when object. (Dynamically allocated objects are allocated with the C++ <b>new</b>
the last <strong>shared_ptr</strong> pointing to it is deleted or reset.&nbsp; expression.) The object pointed to is guaranteed to be deleted when
See <a href="#shared_ptr_example">example</a>.</p> the last <b>shared_ptr</b> pointing to it is destroyed or reset.
<p>Class<strong> shared_ptr</strong> meets the <strong>CopyConstuctible</strong> See the <a href="#example">example</a>.</p>
and <strong>Assignable</strong> requirements of the C++ Standard Library, and so
can be used in C++ Standard Library containers.&nbsp; A specialization of std:: <p>Every <b>shared_ptr</b> meets the <b>CopyConstructible</b>
less&lt; &gt; for&nbsp; boost::shared_ptr&lt;Y&gt; is supplied so that&nbsp;<strong> and <b>Assignable</b> requirements of the C++ Standard Library, and so
shared_ptr</strong> works by default for Standard Library's Associative can be used in standard library containers. Comparison operators
Container Compare template parameter.&nbsp; For compilers not supporting partial are supplied so that <b>shared_ptr</b> works with
specialization, the user must explicitly pass the less&lt;&gt; functor.</p> the standard library's associative containers.</p>
<p>Class<strong> shared_ptr</strong> cannot correctly hold a pointer to a
dynamically allocated array.&nbsp; See <a href="shared_array.htm"><strong>shared_array</strong></a> <p>Normally, a <b>shared_ptr</b> cannot correctly hold a pointer to a
dynamically allocated array. See <a href="shared_array.htm"><b>shared_array</b></a>
for that usage.</p> for that usage.</p>
<p>Class<strong> shared_ptr</strong> will not work correctly with cyclic data
structures. For example, if main() holds a shared_ptr to object A, which
directly or indirectly holds a shared_ptr back to object A, then object A's
use_count() will be 2, and destruction of the main() shared_ptr will leave
object A dangling with a use_count() of 1.</p>
<p>The class is a template parameterized on <tt>T</tt>, the type of the object
pointed to.&nbsp;&nbsp; <tt>T</tt> must meet the smart pointer <a href="smart_ptr.htm#Common requirements">Common
requirements</a>.</p>
<h2>Class shared_ptr <a name="Synopsis"> Synopsis</a></h2>
<pre>#include &lt;<a href="../../boost/smart_ptr.hpp">boost/smart_ptr.hpp</a>&gt;
namespace boost {
template&lt;typename T&gt; class shared_ptr { <p>Because the implementation uses reference counting, <b>shared_ptr</b> will not work
correctly with cyclic data structures. For example, if <b>main()</b> holds a <b>shared_ptr</b>
to <b>A</b>, which directly or indirectly holds a <b>shared_ptr</b> back to <b>A</b>,
<b>A</b>'s use count will be 2. Destruction of the original <b>shared_ptr</b>
will leave <b>A</b> dangling with a use count of 1.</p>
public: <p>The class template is parameterized on <b>T</b>, the type of the object
typedef T <a href="#shared_ptr_element_type">element_type</a>; pointed to. <b>T</b> must meet the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.
<b>T</b> may be <b>void</b>, but in that case, either an explicit delete
function must be passed in, or the pointed-to object must have a trivial destructor.</p>
explicit <a href="#shared_ptr_ctor">shared_ptr</a>( T* p=0 ); <h2><a name="Synopsis">Synopsis</a></h2>
<strong> </strong><a href="#shared_ptr_~shared_ptr">~shared_ptr</a>();
<a href="#shared_ptr_ctor">shared_ptr</a>( const shared_ptr&amp; ); <pre>namespace boost {
template&lt;typename Y&gt;
<a href="#shared_ptr_ctor">shared_ptr</a>(const shared_ptr&lt;Y&gt;&amp; r); // never throws
template&lt;typename Y&gt;
<a href="#shared_ptr_ctor">shared_ptr</a>(std::auto_ptr&lt;Y&gt;&amp; r);
shared_ptr&amp; <a href="#shared_ptr_operator=">operator=</a>( const shared_ptr&amp; ); // never throws template&lt;typename T&gt; class shared_ptr {
template&lt;typename Y&gt;
shared_ptr&amp; <a href="#shared_ptr_operator=">operator=</a>(const shared_ptr&lt;Y&gt;&amp; r); // never throws
template&lt;typename Y&gt;
shared_ptr&amp; <a href="#shared_ptr_operator=">operator=</a>(std::auto_ptr&lt;Y&gt;&amp; r);
void <a href="#shared_ptr_reset">reset</a>( T* p=0 ); public:
typedef T <a href="#element_type">element_type</a>;
T&amp; <a href="#shared_ptr_operator*">operator*</a>() const; // never throws explicit <a href="#constructors">shared_ptr</a>(T * p = 0);
T* <a href="#shared_ptr_operator-&gt;">operator-&gt;</a>() const; // never throws template&lt;typename D&gt; <a href="#constructors">shared_ptr</a>(T * p, D d);
T* <a href="#shared_ptr_get">get</a>() const; // never throws <a href="#destructor">~shared_ptr</a>(); // never throws
long <a href="#shared_ptr_use_count">use_count</a>() const; // never throws <a href="#constructors">shared_ptr</a>(shared_ptr const &amp; r); // never throws
bool <a href="#shared_ptr_unique">unique</a>() const; // never throws template&lt;typename Y&gt; <a href="#constructors">shared_ptr</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws
template&lt;typename Y&gt; <a href="#constructors">shared_ptr</a>(std::auto_ptr&lt;Y&gt; &amp; r);
void <a href="#shared_ptr_swap">swap</a>( shared_ptr&lt;T&gt;&amp; other ) throw() shared_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr const &amp; r); // never throws
}; template&lt;typename Y&gt; shared_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws
template&lt;typename Y&gt; shared_ptr &amp; <a href="#assignment">operator=</a>(std::auto_ptr&lt;Y&gt; &amp; r);
template&lt;typename T, typename U&gt; void <a href="#reset">reset</a>(T * p = 0); // never throws
inline bool operator==(const shared_ptr&lt;T&gt;&amp; a, const shared_ptr&lt;U&gt;&amp; b) template&lt;typename D&gt; void <a href="#reset">reset</a>(T * p, D d); // never throws
{ return a.get() == b.get(); }
template&lt;typename T, typename U&gt; T &amp; <a href="#indirection">operator*</a>() const; // never throws
inline bool operator!=(const shared_ptr&lt;T&gt;&amp; a, const shared_ptr&lt;U&gt;&amp; b) T * <a href="#indirection">operator-&gt;</a>() const; // never throws
{ return a.get() != b.get(); } T * <a href="#get">get</a>() const; // never throws
}</pre>
<pre>namespace std {
template&lt;typename T&gt; bool <a href="#unique">unique</a>() const; // never throws
inline void swap(boost::shared_ptr&lt;T&gt;&amp; a, boost::shared_ptr&lt;T&gt;&amp; b) long <a href="#use_count">use_count</a>() const; // never throws
{ a.swap(b); }
template&lt;typename T&gt; void <a href="#swap">swap</a>(shared_ptr&lt;T&gt; &amp; b); // never throws
struct less&lt; boost::shared_ptr&lt;T&gt; &gt;
: binary_function&lt;boost::shared_ptr&lt;T&gt;, boost::shared_ptr&lt;T&gt;, bool&gt;
{
bool operator()(const boost::shared_ptr&lt;T&gt;&amp; a,
const boost::shared_ptr&lt;T&gt;&amp; b) const
{ return less&lt;T*&gt;()(a.get(),b.get()); }
}; };
} // namespace std </pre> template&lt;typename T, typename U&gt;
<p>Specialization of std::swap uses the fast, non-throwing swap that's provided bool <a href="#operator==">operator==</a>(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws
as a member function instead of using the default algorithm which creates a template&lt;typename T, typename U&gt;
temporary and uses assignment.<br> bool <a href="#operator!=">operator!=</a>(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws
<br> template&lt;typename T, typename U&gt;
Specialization of std::less allows use of shared pointers as keys in&nbsp;C++ bool <a href="#operator&lt;">operator&lt;</a>(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws
Standard Library associative collections.<br>
<br> template&lt;typename T&gt; void <a href="#free-swap">swap</a>(shared_ptr&lt;T&gt; &amp; a, shared_ptr&lt;T&gt; &amp; b); // never throws
The std::less specializations use std::less&lt;T*&gt; to perform the
comparison.&nbsp; This insures that pointers are handled correctly, since the template&lt;typename T, typename U&gt;
standard mandates that relational operations on pointers are unspecified (5.9 [expr.rel] shared_ptr&lt;T&gt <a href="#shared_static_cast">shared_static_cast</a>(shared_ptr&lt;U&gt; const &amp; r); // never throws
paragraph 2) but std::less&lt;&gt; on pointers is well-defined (20.3.3 [lib.comparisons] template&lt;typename T, typename U&gt;
paragraph 8).<br> shared_ptr&lt;T&gt <a href="#shared_dynamic_cast">shared_dynamic_cast</a>(shared_ptr&lt;U&gt; const &amp; r);
<br>
It's still a controversial question whether supplying only std::less is better }</pre>
than supplying a full range of comparison operators (&lt;, &gt;, &lt;=, &gt;=).</p>
<p>The current implementation does not supply the specializations if the macro <h2><a name="Members">Members</a></h2>
name BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION is defined.</p>
<p>The current implementation does not supply the member template functions if <h3><a name="element_type">element_type</a></h3>
the macro name BOOST_NO_MEMBER_TEMPLATES is defined.</p>
<h2>Class shared_ptr <a name="Members"> Members</a></h2>
<h3>shared_ptr <a name="shared_ptr_element_type">element_type</a></h3>
<pre>typedef T element_type;</pre> <pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p> <p>Provides the type of the stored pointer.</p>
<h3><a name="shared_ptr_ctor">shared_ptr constructors</a></h3>
<pre>explicit shared_ptr( T* p=0 );</pre> <h3><a name="constructors">constructors</a></h3>
<p>Constructs a <strong>shared_ptr</strong>, storing a copy of <tt>p</tt>, which
must have been allocated via a C++ <tt>new</tt> expression or be 0. Afterwards, <strong>use_count()</strong> <pre>explicit shared_ptr(T * p = 0);</pre>
is 1 (even if p==0; see <a href="#shared_ptr_~shared_ptr">~shared_ptr</a>).</p> <p>Constructs a <b>shared_ptr</b>, storing a copy of <b>p</b>, which
<p>The only exception which may be thrown by this constructor is <tt>std::bad_alloc</tt>.&nbsp;&nbsp; must be a pointer to an object that was allocated via a C++ <b>new</b> expression or be 0.
If an exception is thrown,&nbsp; <tt>delete p</tt> is called.</p> Afterwards, the <a href="#use_count">use count</a> is 1 (even if p == 0; see <a href="#destructor">~shared_ptr</a>).
<pre>shared_ptr( const shared_ptr&amp; r); // never throws The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
template&lt;typename Y&gt; If an exception is thrown, <b>delete p</b> is called.</p>
shared_ptr(const shared_ptr&lt;Y&gt;&amp; r); // never throws
template&lt;typename Y&gt; <pre>template&lt;typename D&gt; shared_ptr(T * p, D d);</pre>
shared_ptr(std::auto_ptr&lt;Y&gt;&amp; r);</pre> <p>Constructs a <b>shared_ptr</b>, storing a copy of <b>p</b> and of <b>d</b>.
<p>Constructs a <strong>shared_ptr</strong>, as if by storing a copy of the Afterwards, the <a href="#use_count">use count</a> is 1.
pointer stored in <strong>r</strong>. Afterwards, <strong>use_count()</strong> <b>D</b>'s copy constructor must not throw.
for all copies is 1 more than the initial <strong>r.use_count()</strong>, or 1 When the the time comes to delete the object pointed to by <b>p</b>, the object
in the <strong>auto_ptr</strong> case. In the <strong>auto_ptr</strong> case, <strong>r.release()</strong> <b>d</b> is used in the statement <b>d(p)</b>. Invoking the object <b>d</b> with
is called.</p> parameter <b>p</b> in this way must not throw.
<p>The only exception which may be thrown by the constructor from <strong>auto_ptr</strong> The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
is <tt>std::bad_alloc</tt>.&nbsp;&nbsp; If an exception is thrown, that If an exception is thrown, <b>d(p)</b> is called.</p>
constructor has no effect.</p>
<h3><a name="shared_ptr_~shared_ptr">shared_ptr destructor</a></h3> <pre>shared_ptr(shared_ptr const &amp; r); // never throws
<pre>~shared_ptr();</pre> template&lt;typename Y&gt; shared_ptr(shared_ptr&lt;Y&gt; const &amp; r); // never throws
<p>If <strong>use_count()</strong> == 1, deletes the object pointed to by the template&lt;typename Y&gt; shared_ptr(std::auto_ptr&lt;Y&gt; &amp; r);</pre>
stored pointer.&nbsp;Otherwise, <strong>use_count()</strong> for any remaining <p>Constructs a <b>shared_ptr</b>, as if by storing a copy of the
copies is decremented by 1. Note that in C++&nbsp; <tt>delete</tt> on a pointer pointer stored in <b>r</b>. Afterwards, the <a href="#use_count">use count</a>
with a value of 0 is harmless.</p> for all copies is 1 more than the initial use count, or 1
<p>Does not throw exceptions.</p> in the <b>auto_ptr</b> case. In the <b>auto_ptr</b> case, <b>r.release()</b>
<h3>shared_ptr <a name="shared_ptr_operator=">operator=</a></h3> is called.
<pre>shared_ptr&amp; operator=( const shared_ptr&amp; r); The only exception which may be thrown is <b>std::bad_alloc</b>,
template&lt;typename Y&gt; which may be thrown during construction from <b>auto_ptr</b>.
shared_ptr&amp; operator=(const shared_ptr&lt;Y&gt;&amp; r); If an exception is thrown, the constructor has no effect.</p>
template&lt;typename Y&gt;
shared_ptr&amp; operator=(std::auto_ptr&lt;Y&gt;&amp; r);</pre> <h3><a name="destructor">destructor</a></h3>
<p>First, if <strong>use_count()</strong> == 1, deletes the object pointed to by
the stored pointer.&nbsp;Otherwise, <strong>use_count()</strong> for any <pre>~shared_ptr(); // never throws</pre>
remaining copies is decremented by 1. Note that in C++&nbsp; <tt>delete</tt> on <p>Decrements the <a href="#use_count">use count</a>. Then, if the use count is 0,
a pointer with a value of 0 is harmless.</p> deletes the object pointed to by the stored pointer.
<p>Then replaces the contents of <strong>this</strong>, as if by storing a copy Note that <b>delete</b> on a pointer with a value of 0 is harmless.
of the pointer stored in <strong>r</strong>. Afterwards, <strong>use_count()</strong> <b>T</b> need not be a complete type.
for all copies is 1 more than the initial <strong>r.use_count()</strong>, or 1 The guarantee that this does not throw exceptions depends on the requirement that the
in the <strong>auto_ptr</strong> case. In the <strong>auto_ptr</strong> case, <strong>r.release()</strong> deleted object's destructor does not throw exceptions.
is called.</p> See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>The first two forms of <tt>operator=</tt> above do not throw exceptions.</p>
<p>The only exception which may be thrown by the <strong>auto_ptr</strong> form <h3><a name="operator=">assignment</a></h3>
is <tt>std::bad_alloc</tt>.&nbsp;&nbsp; If an exception is thrown, the function
has no effect.</p> <pre>shared_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr const &amp; r); // never throws
<h3>shared_ptr <a name="shared_ptr_reset">reset</a></h3> template&lt;typename Y&gt; shared_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws
<pre>void reset( T* p=0 );</pre> template&lt;typename Y&gt; shared_ptr &amp; <a href="#assignment">operator=</a>(std::auto_ptr&lt;Y&gt; &amp; r);</pre>
<p>First, if <strong>use_count()</strong> == 1, deletes the object pointed to by <p>Constructs a new <b>shared_ptr</b> as described <a href="#constructors">above</a>,
the stored pointer.&nbsp;Otherwise, <strong>use_count()</strong> for any then replaces this <b>shared_ptr</b> with the new one, destroying the replaced object.
remaining copies is decremented by 1.&nbsp;</p> The only exception which may be thrown is <b>std::bad_alloc</b>,
<p>Then replaces the contents of <strong>this</strong>, as if by storing a copy which may be thrown during assignment from <b>auto_ptr</b>.
of <strong>p</strong>, which must have been allocated via a C++ <tt>new</tt> If an exception is thrown, the assignment has no effect.</p>
expression or be 0. Afterwards, <strong>use_count()</strong> is 1 (even if p==0;
see <a href="#shared_ptr_~shared_ptr">~shared_ptr</a>). Note that in C++&nbsp; <tt>delete</tt> <h3><a name="reset">reset</a></h3>
on a pointer with a value of 0 is harmless.</p>
<p>The only exception which may be thrown is <tt>std::bad_alloc</tt>.&nbsp; If <pre>void reset(T * p = 0);</pre>
an exception is thrown,&nbsp; <tt>delete p</tt> is called.</p> <p>Constructs a new <b>shared_ptr</b> as described <a href="#constructors">above</a>,
<h3>shared_ptr <a name="shared_ptr_operator*">operator*</a></h3> then replaces this <b>shared_ptr</b> with the new one, destroying the replaced object.
<pre>T&amp; operator*() const; // never throws</pre> The only exception which may be thrown is <b>std::bad_alloc</b>. If
<p>Returns a reference to the object pointed to by the stored pointer.</p> an exception is thrown, <b>delete p</b> is called.</p>
<h3>shared_ptr <a name="shared_ptr_operator-&gt;">operator-&gt;</a> and <a name="shared_ptr_get">get</a></h3>
<pre>T* operator-&gt;() const; // never throws <pre>template&lt;typename D&gt; void reset(T * p, D d);</pre>
T* get() const; // never throws</pre> <p>Constructs a new <b>shared_ptr</b> as described <a href="#constructors">above</a>,
<p><b>T</b> is not required by get() to be a complete type .&nbsp; See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> then replaces this <b>shared_ptr</b> with the new one, destroying the replaced object.
<p>Both return the stored pointer.</p> <b>D</b>'s copy constructor must not throw.
<h3>shared_ptr<a name="shared_ptr_use_count"> use_count</a></h3> The only exception which may be thrown is <b>std::bad_alloc</b>. If
<p><tt>long use_count() const; // never throws</tt></p> an exception is thrown, <b>d(p)</b> is called.</p>
<p><b>T</b> is not required be a complete type.&nbsp;
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> <h3><a name="indirection">indirection</a></h3>
<p>Returns the number of <strong>shared_ptrs</strong> sharing ownership of the <pre>T &amp; operator*() const; // never throws</pre>
stored pointer.</p> <p>Returns a reference to the object pointed to by the stored pointer.
<h3>shared_ptr <a name="shared_ptr_unique">unique</a></h3> Behavior is undefined if the stored pointer is 0.</p>
<p><tt>bool unique() const; // never throws</tt></p> <pre>T * operator-&gt;() const; // never throws</pre>
<p><b>T</b> is not required be a complete type.&nbsp; <p>Returns the stored pointer. Behavior is undefined if the stored pointer is 0.</p>
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p>
<p>Returns <strong>use_count()</strong> == 1.</p> <h3><a name="get">get</a></h3>
<h3><a name="shared_ptr_swap">shared_ptr swap</a></h3> <pre>T * get() const; // never throws</pre>
<p><code>void swap( shared_ptr&lt;T&gt;&amp; other ) throw()</code></p> <p>Returns the stored pointer.
<p><b>T</b> is not required be a complete type.&nbsp; <b>T</b> need not be a complete type.
See <a href="smart_ptr.htm#Common requirements">Common Requirements</a>.</p> See the smart pointer
<p>Swaps the two smart pointers, as if by std::swap.</p> <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h2>Class <a name="shared_ptr_example">shared_ptr example</a></h2>
<p>See <a href="shared_ptr_example.cpp"> shared_ptr_example.cpp</a> for a complete example program.</p> <h3><a name="unique">unique</a></h3>
<p>This program builds a std::vector and std::set of FooPtr's.</p> <pre>bool unique() const; // never throws</pre>
<p>Note that after the two containers have been populated, some of the FooPtr objects <p>Returns true if no other <b>shared_ptr</b> is sharing ownership of
will have use_count()==1 rather than use_count()==2, since foo_set is a std::set the stored pointer, false otherwise.
rather than a std::multiset, and thus does not contain duplicate entries.&nbsp; Furthermore, use_count() may be even higher <b>T</b> need not be a complete type.
at various times while push_back() and insert() container operations are performed.&nbsp; See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="use_count">use_count</a></h3>
<pre>long use_count() const; // never throws</pre>
<p>Returns the number of <b>shared_ptr</b> objects sharing ownership of the
stored pointer.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Because <b>use_count</b> is not necessarily efficient to implement for
implementations of <b>shared_ptr</b> 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.</p>
<h3><a name="swap">swap</a></h3>
<pre>void swap(shared_ptr &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2>
<h3><a name="comparison">comparison</a></h3>
<pre>template&lt;typename T, typename U&gt;
bool <a href="#operator==">operator==</a>(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws
template&lt;typename T, typename U&gt;
bool <a href="#operator!=">operator!=</a>(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws
template&lt;typename T, typename U&gt;
bool <a href="#operator&lt;">operator&lt;</a>(shared_ptr&lt;T&gt; const &amp; a, shared_ptr&lt;U&gt; const &amp; b); // never throws</pre>
<p>Compares the stored pointers of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>The <b>operator&lt;</b> overload is provided to define an ordering so that <b>shared_ptr</b>
objects can be used in associative containers such as <b>std::map</b>.
The implementation uses std::less&lt;T*&gt; 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&lt;&gt; on pointers is well-defined (20.3.3 [lib.comparisons]
paragraph 8).</p>
<h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt;
void swap(shared_ptr&lt;T&gt; &amp; a, shared_ptr&lt;T&gt; &amp; b) // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p>
<h3><a name="shared_static_cast">shared_static_cast</a></h3>
<pre>template&lt;typename T, typename U&gt;
shared_ptr&lt;T&gt <a href="#shared_static_cast">shared_static_cast</a>(shared_ptr&lt;U&gt; const &amp; r); // never throws</pre>
<p>Perform a <b>static_cast</b> on the stored pointer, returning another <b>shared_ptr</b>.
The resulting smart pointer will share its use count with the original pointer.</p>
<p>Note that the seemingly equivalent expression</p>
<blockquote><code>shared_ptr&lt;T&gt;(static_cast&lt;T*&gt;(r.get()))</code></blockquote>
<p>will eventually result in undefined behavior, attempting to delete the same object twice.</p>
<h3><a name="shared_dynamic_cast">shared_dynamic_cast</a></h3>
<pre>template&lt;typename T, typename U&gt;
shared_ptr&lt;T&gt <a href="#shared_dynamic_cast">shared_dynamic_cast</a>(shared_ptr&lt;U&gt; const &amp; r);</pre>
<p>Perform a <b>dynamic_cast</b> on the stored pointer, returning another <b>shared_ptr</b>.
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 <b>std::bad_alloc</b>, which may be thrown during the
construction of the new <b>shared_ptr</b> if the result of the cast is 0. If an exception is thrown, the
cast has no effect.</p>
<p>Note that the seemingly equivalent expression</p>
<blockquote><code>shared_ptr&lt;T&gt;(dynamic_cast&lt;T*&gt;(r.get()))</code></blockquote>
<p>will eventually result in undefined behavior, attempting to delete the same object twice.</p>
<h2><a name="example">Example</a></h2>
<p>See <a href="shared_ptr_example.cpp">shared_ptr_example.cpp</a> for a complete example program.
The program builds a <b>std::vector</b> and <b>std::set</b> of <b>shared_ptr</b> objects.</p>
<p>Note that after the containers have been populated, some of the <b>shared_ptr</b> objects
will have a use count of 1 rather than a use count of 2, since the set is a <b>std::set</b>
rather than a <b>std::multiset</b>, and thus does not contain duplicate entries.
Furthermore, the use count may be even higher
at various times while <b>push_back</b> and <b>insert</b> container operations are performed.
More complicated yet, the container operations may throw exceptions under a More complicated yet, the container operations may throw exceptions under a
variety of circumstances.&nbsp; Without using a smart pointer, memory and variety of circumstances. Getting the memory management and exception handling in this
exception management would be a nightmare.</p> example right without a smart pointer would be a nightmare.</p>
<h2><a name="Handle/Body">Handle/Body</a> Idiom</h2> <h2><a name="Handle/Body">Handle/Body</a> Idiom</h2>
<p>One common usage of <b>shared_ptr</b> is to implement a handle/body (also <p>One common usage of <b>shared_ptr</b> is to implement a handle/body (also
called pimpl) idiom which avoids exposing the body (implementation) in the header called pimpl) idiom which avoids exposing the body (implementation) in the header
file.</p> file.</p>
<p>The <a href="shared_ptr_example2_test.cpp">shared_ptr_example2_test.cpp</a> <p>The <a href="shared_ptr_example2_test.cpp">shared_ptr_example2_test.cpp</a>
sample program includes a header file, <a href="shared_ptr_example2.hpp">shared_ptr_example2.hpp</a>, sample program includes a header file, <a href="shared_ptr_example2.hpp">shared_ptr_example2.hpp</a>,
which uses a <b>shared_ptr&lt;&gt;</b> to an incomplete type to hide the which uses a <b>shared_ptr&lt;&gt;</b> to an incomplete type to hide the
implementation.&nbsp;&nbsp; The implementation. The
instantiation of member functions which require a complete type occurs in the <a href="shared_ptr_example2.cpp">shared_ptr_example2.cpp</a> instantiation of member functions which require a complete type occurs in the
implementation file.</p> <a href="shared_ptr_example2.cpp">shared_ptr_example2.cpp</a>
implementation file.
Note that there is no need for an explicit destructor.
Unlike ~scoped_ptr, ~shared_ptr does not require that <b>T</b> be a complete type.</p>
<h2><a name="FAQ">Frequently Asked Questions</a></h2> <h2><a name="FAQ">Frequently Asked Questions</a></h2>
<p><b>Q.</b> Why doesn't <b>shared_ptr</b> have template parameters supplying <p><b>Q.</b> Why doesn't <b>shared_ptr</b> have template parameters supplying
traits or policies to allow extensive user customization?<br> traits or policies to allow extensive user customization?<br>
<b>A.</b> Parameterization discourages users.&nbsp; <b>Shared_ptr</b> is <b>A.</b> Parameterization discourages users. The <b>shared_ptr</b> template is
carefully crafted to meet common needs without extensive parameterization. carefully crafted to meet common needs without extensive parameterization.
Someday a highly configurable smart pointer may be invented that is also very Some day a highly configurable smart pointer may be invented that is also very
easy to use and very hard to misuse.&nbsp; Until then, <b>shared_ptr</b> is the easy to use and very hard to misuse. Until then, <b>shared_ptr</b> is the
smart pointer of choice for a wide range of applications.&nbsp; (Those smart pointer of choice for a wide range of applications. (Those
interested in policy based smart pointers should read <a href="http://cseng.aw.com/book/0,,0201704315,00.html">Modern interested in policy based smart pointers should read
C++ Design</a> by Andrei Alexandrescu.)</p> <a href="http://cseng.aw.com/book/0,,0201704315,00.html">Modern C++ Design</a> by Andrei Alexandrescu.)</p>
<p><b>Q.</b> Why doesn't <b>shared_ptr</b> use a linked list implementation?<br> <p><b>Q.</b> Why doesn't <b>shared_ptr</b> use a linked list implementation?<br>
<b>A.</b> A linked list implementation does not offer enough advantages to <b>A.</b> A linked list implementation does not offer enough advantages to
offset the added cost of an extra pointer.&nbsp; See <a href="smarttests.htm">timings</a> offset the added cost of an extra pointer. See <a href="smarttests.htm">timings</a>
page.</p> page.</p>
<p><b>Q.</b> Why don't <b>shared_ptr</b> (and the other Boost smart pointers)
<p><b>Q.</b> Why doesn't <b>shared_ptr</b> (or any of the other Boost smart pointers)
supply an automatic conversion to <b>T*</b>?<br> supply an automatic conversion to <b>T*</b>?<br>
<b>A.</b> Automatic conversion is believed to be too error prone.</p> <b>A.</b> Automatic conversion is believed to be too error prone.</p>
<p><b>Q.</b> Why does <b>shared_ptr</b> supply use_count()?<br> <p><b>Q.</b> Why does <b>shared_ptr</b> supply use_count()?<br>
<b>A.</b> As an aid to writing test cases and debugging displays. One of the <b>A.</b> 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 progenitors had use_count(), and it was useful in tracking down bugs in a
complex project that turned out to have cyclic-dependencies.</p> complex project that turned out to have cyclic-dependencies.</p>
<p><b>Q.</b> Why doesn't <b>shared_ptr</b> specify complexity requirements?<br> <p><b>Q.</b> Why doesn't <b>shared_ptr</b> specify complexity requirements?<br>
<b>A.</b> Because complexity limit implementors and complicate the specification without apparent benefit to <b>A.</b> Because complexity requirements limit implementors and complicate the
<b>shared_ptr</b> users. For example, error-checking implementations might become non-conforming if they specification without apparent benefit to <b>shared_ptr</b> users.
For example, error-checking implementations might become non-conforming if they
had to meet stringent complexity requirements.</p> had to meet stringent complexity requirements.</p>
<p><b>Q.</b> Why doesn't <b>shared_ptr</b> provide a release() function?<br> <p><b>Q.</b> Why doesn't <b>shared_ptr</b> provide a release() function?<br>
<b>A.</b> <b>shared_ptr</b> cannot give away ownership unless it's unique() <b>A.</b> <b>shared_ptr</b> cannot give away ownership unless it's unique()
because the other copy will still destroy the object.</p> because the other copy will still destroy the object.</p>
<p>Consider:</p> <p>Consider:</p>
<blockquote> <blockquote><pre>shared_ptr&lt;int&gt; a(new int);
<pre>shared_ptr&lt;int&gt; a(new int);
shared_ptr&lt;int&gt; b(a); // a.use_count() == b.use_count() == 2 shared_ptr&lt;int&gt; b(a); // a.use_count() == b.use_count() == 2
int * p = a.release(); int * p = a.release();
// Who owns p now? b will still call delete on it in its destructor.</pre> // Who owns p now? b will still call delete on it in its destructor.</pre></blockquote>
</blockquote>
<p>[Provided by Peter Dimov]</p>
<p><b>Q.</b> Why doesn't <b>shared_ptr</b> provide (your pet feature here)?<br> <p><b>Q.</b> Why doesn't <b>shared_ptr</b> provide (your pet feature here)?<br>
<b>A.</b> Because (your pet feature here) would mandate a reference counted (or a link-list, or ...) implementation. This is not the intent. <b>A.</b> Because (your pet feature here) would mandate a reference counted
[Provided by Peter Dimov]</p> implementation or a linked list implementation, or some other specific implementation.
<p><br> This is not the intent.</p>
</p>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->11 January, 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan -->
</p> <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->1 February 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
<p><EFBFBD> Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use,
modify, sell and distribute this document is granted provided this copyright <p>Copyright 1999 Greg Colvin and Beman Dawes. Copyright 2002 Darin Adler.
notice appears in all copies. This document is provided &quot;as is&quot; Permission to copy, use, modify, sell and distribute this document is granted
without express or implied warranty, and with no claim as to its suitability for provided this copyright notice appears in all copies.
any purpose.</p> This document is provided &quot;as is&quot; without express or implied warranty,
and with no claim as to its suitability for any purpose.</p>
</body> </body>
</html> </html>

View File

@ -20,7 +20,7 @@
#include <set> #include <set>
#include <iostream> #include <iostream>
#include <algorithm> #include <algorithm>
#include <boost/smart_ptr.hpp> #include <boost/shared_ptr.hpp>
// The application will produce a series of // The application will produce a series of
// objects of type Foo which later must be // objects of type Foo which later must be

View File

@ -17,5 +17,3 @@ example & example::operator=( const example & s )
void example::do_something() void example::do_something()
{ std::cout << "use_count() is " << _imp.use_count() << "\n"; } { std::cout << "use_count() is " << _imp.use_count() << "\n"; }
example::~example() {}

View File

@ -1,6 +1,6 @@
// Boost shared_ptr_example2 header file -----------------------------------// // Boost shared_ptr_example2 header file -----------------------------------//
#include <boost/smart_ptr.hpp> #include <boost/shared_ptr.hpp>
// This example demonstrates the handle/body idiom (also called pimpl and // This example demonstrates the handle/body idiom (also called pimpl and
// several other names). It separates the interface (in this header file) // several other names). It separates the interface (in this header file)
@ -16,7 +16,6 @@ class example
{ {
public: public:
example(); example();
~example();
example( const example & ); example( const example & );
example & operator=( const example & ); example & operator=( const example & );
void do_something(); void do_something();

View File

@ -1,126 +1,175 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage 4.0"> <title>Smart Pointers</title>
<meta name="ProgId" content="FrontPage.Editor.Document">
<title>Smart Pointer Classes</title>
</head> </head>
<body bgcolor="#FFFFFF" text="#000000"> <body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" width="277" height="86">Smart <h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">Smart
Pointers</h1> Pointers</h1>
<p>Smart pointers are classes which store pointers to dynamically allocated
(heap) objects.&nbsp; They behave much like built-in C++ pointers except that <p>Smart 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 they automatically delete the object pointed to at the appropriate
time.&nbsp;Smart pointers are particularly useful in the face of exceptions as time. Smart pointers are particularly useful in the face of exceptions as
they ensure proper destruction of dynamically allocated objects. They can also they ensure proper destruction of dynamically allocated objects. They can also
be used to keep track of dynamically allocated objects shared by multiple be used to keep track of dynamically allocated objects shared by multiple
owners.</p> owners.</p>
<p>Conceptually, smart pointers are seen as owning the object pointed to, and <p>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.</p> thus responsible for deletion of the object when it is no longer needed.</p>
<p>The header <a href="../../boost/smart_ptr.hpp">boost/smart_ptr.hpp</a>
provides four smart pointer template classes:</p> <p>The smart pointer library provides five smart pointer class templates:</p>
<div align="left"> <div align="left">
<table border="1" cellpadding="4" cellspacing="4"> <table border="1" cellpadding="4" cellspacing="4">
<tr> <tr>
<td> <td><a href="scoped_ptr.htm"><b>scoped_ptr</b></a></td>
<p align="left"><a href="scoped_ptr.htm"><strong>scoped_ptr</strong></a></td> <td><a href="../boost/scoped_ptr.hpp">&lt;boost/scoped_ptr.hpp&gt;</a></td>
<td>Simple sole ownership of single objects. Noncopyable.</td> <td>Simple sole ownership of single objects. Noncopyable.</td>
</tr> </tr>
<tr> <tr>
<td><a href="scoped_array.htm"><strong>scoped_array</strong></a></td> <td><a href="scoped_array.htm"><b>scoped_array</b></a></td>
<td>Simple sole ownership of arrays. Noncopyable.</td> <td><a href="../boost/scoped_array.hpp">&lt;boost/scoped_array.hpp&gt;</a></td>
<td>Simple sole ownership of arrays. Noncopyable.</td>
</tr> </tr>
<tr> <tr>
<td><a href="shared_ptr.htm"><strong>shared_ptr</strong></a></td> <td><a href="shared_ptr.htm"><b>shared_ptr</b></a></td>
<td><a href="../boost/shared_ptr.hpp">&lt;boost/shared_ptr.hpp&gt;</a></td>
<td>Object ownership shared among multiple pointers</td> <td>Object ownership shared among multiple pointers</td>
</tr> </tr>
<tr> <tr>
<td><a href="shared_array.htm"><strong>shared_array</strong></a></td> <td><a href="shared_array.htm"><b>shared_array</b></a></td>
<td><a href="../boost/shared_array.hpp">&lt;boost/shared_array.hpp&gt;</a></td>
<td>Array ownership shared among multiple pointers.</td> <td>Array ownership shared among multiple pointers.</td>
</tr> </tr>
<tr>
<td><a href="weak_ptr.htm"><b>weak_ptr</b></a></td>
<td><a href="../boost/weak_ptr.hpp">&lt;boost/weak_ptr.hpp&gt;</a></td>
<td>Non-owning observers of an object owned by <b>shared_ptr</b>.</td>
</tr>
</table> </table>
</div> </div>
<p>These classes are designed to complement the C++ Standard Library <tt>auto_ptr</tt>
class.</p> <p>These templates are designed to complement the <b>std::auto_ptr</b> template.</p>
<p>They are examples of the &quot;resource acquisition is initialization&quot; <p>They are examples of the &quot;resource acquisition is initialization&quot;
idiom described in Bjarne Stroustrup's &quot;The C++ Programming Language&quot;, idiom described in Bjarne Stroustrup's &quot;The C++ Programming Language&quot;,
3rd edition, Section 14.4, Resource Management.</p> 3rd edition, Section 14.4, Resource Management.</p>
<p>A test program (<a href="smart_ptr_test.cpp">smart_ptr_test.cpp</a>) is
<p>A test program, <a href="smart_ptr_test.cpp">smart_ptr_test.cpp</a>, is
provided to verify correct operation.</p> provided to verify correct operation.</p>
<p>A page on <a href="smarttests.htm">Smart Pointer Timings</a> will be of
<p>A page on <a href="compatibility.htm">compatibility</a> with older versions of
the Boost smart pointer library describes some of the changes since earlier versions
of the smart pointer implementation.</p>
<p>A page on <a href="smarttests.htm">smart pointer timings</a> will be of
interest to those curious about performance issues.</p> interest to those curious about performance issues.</p>
<h2><a name="Common requirements">Common requirements</a></h2>
<p>These smart pointer classes have a template parameter, <tt><b>T</b></tt>, which <h2><a name="Common requirements">Common Requirements</a></h2>
specifies the type of the object pointed to by the smart pointer.&nbsp; The
behavior of all four classes is undefined if the destructor or operator delete <p>These smart pointer class templates have a template parameter, <b>T</b>, which
for objects of type <tt><b>T</b></tt> throw exceptions.</p> specifies the type of the object pointed to by the smart pointer. The
<p><code><b>T</b></code> may be an incomplete type at the point of smart pointer behavior of the smart pointer templates is undefined if the destructor or <b>operator delete</b>
declaration.&nbsp; Unless otherwise specified, it is required that <code><b>T</b></code> for objects of type <b>T</b> throw exceptions.</p>
<p><b>T</b> may be an incomplete type at the point of smart pointer
declaration. Unless otherwise specified, it is required that <b>T</b>
be a complete type at points of smart pointer instantiation. Implementations are be a complete type at points of smart pointer instantiation. Implementations are
required to diagnose (treat as an error) all violations of this requirement, required to diagnose (treat as an error) all violations of this requirement,
including deletion of an incomplete type. See <a href="../utility/utility.htm#checked_delete">checked_delete()</a>.</p> including deletion of an incomplete type.
See the description of the <a href="../utility/utility.htm#checked_delete"><b>checked_delete</b></a>
function template.</p>
<h3>Rationale</h3> <h3>Rationale</h3>
<p>The requirements on <tt><b>T</b></tt> are carefully crafted to maximize safety
yet allow handle-body (also called pimpl) and similar idioms.&nbsp; In these idioms a <p>The requirements on <b>T</b> are carefully crafted to maximize safety
smart pointer may appear in translation units where <tt><b>T</b></tt> is an yet allow handle-body (also called pimpl) and similar idioms. In these idioms a
incomplete type.&nbsp; This separates interface from implementation and hides smart pointer may appear in translation units where <b>T</b> is an
implementation from translation units which merely use the interface.&nbsp; 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 Examples described in the documentation for specific smart pointers illustrate
use of smart pointers in these idioms.</p> use of smart pointers in these idioms.</p>
<h2>Exception safety</h2>
<p>Note that <b>scoped_ptr</b> requires that <b>T</b> be a complete type
at destruction time, but <b>shared_ptr</b> does not.</p>
<h2>Exception Safety</h2>
<p>Several functions in these smart pointer classes are specified as having <p>Several functions in these smart pointer classes are specified as having
&quot;no effect&quot; or &quot;no effect except such-and-such&quot; if an &quot;no effect&quot; or &quot;no effect except such-and-such&quot; if an
exception is thrown.&nbsp;&nbsp; This means that when an exception is thrown by 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 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 it was prior to the function call which resulted in the exception being
thrown.&nbsp; This amounts to a guarantee that there are no detectable side thrown. This amounts to a guarantee that there are no detectable side
effects.&nbsp;&nbsp; Other functions never throw exceptions. The only exception effects. Other functions never throw exceptions. The only exception
ever thrown by functions which do throw (assuming <tt>T</tt> meets the <a href="#Common requirements">Common ever thrown by functions which do throw (assuming <b>T</b> meets the
requirements</a>)&nbsp; is <tt>std::bad_alloc</tt>, and that is thrown only by <a href="#Common requirements">common requirements</a>) is <b>std::bad_alloc</b>,
functions which are explicitly documented as possibly throwing <tt>std::bad_alloc</tt>.</p> and that is thrown only by functions which are explicitly documented as possibly
throwing <b>std::bad_alloc</b>.</p>
<h2>Exception-specifications</h2> <h2>Exception-specifications</h2>
<p>Exception-specifications are not used; see <a href="../../more/lib_guide.htm#Exception-specification">exception-specification
<p>Exception-specifications are not used; see
<a href="../../more/lib_guide.htm#Exception-specification">exception-specification
rationale</a>.</p> rationale</a>.</p>
<p>All four classes contain member functions which can never throw exceptions,
<p>All the smart pointer templates contain member functions which can never throw exceptions,
because they neither throw exceptions themselves nor call other functions which because they neither throw exceptions themselves nor call other functions which
may throw exceptions.&nbsp; These members are indicated by a comment: <kbd>// may throw exceptions. These members are indicated by a comment:
never throws</kbd>. </p> <code>// never throws</code>. </p>
<p>Functions which destroy objects of the pointed to type are prohibited from <p>Functions which destroy objects of the pointed to type are prohibited from
throwing exceptions by the <a href="#Common requirements">Common requirements</a>.</p> throwing exceptions by the <a href="#Common requirements">common requirements</a>.</p>
<h2>History and acknowledgements</h2>
<p>May, 2001. Vladimir Prus suggested requiring a complete type on <h2>History and Acknowledgements</h2>
destruction.&nbsp; Refinement evolved in discussions including Dave Abrahams,
<p>January 2002. Peter Dimov reworked all four classes, adding features, fixing bugs,
and splitting them into four separate headers, and added <b>weak_ptr</b>. See the
<a href="compatibility.htm">compatibility</a> page for a summary of the changes.</p>
<p>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, Greg Colvin, Beman Dawes, Rainer Deyke, Peter Dimov, John Maddock, Vladimir Prus,
Shankar Sai, and others.</p> Shankar Sai, and others.</p>
<p>November, 1999. Darin Adler provided operator ==, operator !=, and std::swap
<p>November 1999. Darin Adler provided operator ==, operator !=, and std::swap
and std::less specializations for shared types.</p> and std::less specializations for shared types.</p>
<p>September, 1999. Luis Coelho provided shared_ptr::swap and shared_array::swap</p>
<p>May, 1999.&nbsp; In April and May, 1999, Valentin Bonnard and David Abrahams <p>September 1999. Luis Coelho provided shared_ptr::swap and shared_array::swap</p>
made a number of suggestions resulting in numerous improvements.&nbsp; See the
revision history in <a href="../../boost/smart_ptr.hpp"><tt>smart_ptr.hpp</tt></a> <p>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 <a href="../../boost/smart_ptr.hpp"><b>smart_ptr.hpp</b></a>
for the specific changes made as a result of their constructive criticism.</p> for the specific changes made as a result of their constructive criticism.</p>
<p>Oct, 1998.&nbsp; In 1994 Greg Colvin proposed to the C++ Standards Committee
classes named <strong>auto_ptr</strong> and <strong>counted_ptr</strong> which <p>October 1998. In 1994 Greg Colvin proposed to the C++ Standards Committee
were very similar to what we now call <strong>scoped_ptr</strong> and <strong>shared_ptr</strong>.&nbsp; classes named <b>auto_ptr</b> and <b>counted_ptr</b> which
The committee document was 94-168/N0555, Exception Safe Smart Pointers.&nbsp; In were very similar to what we now call <b>scoped_ptr</b> and <b>shared_ptr</b>.
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 one of the very few cases where the Library Working Group's recommendations were
not followed by the full committee, <strong>counted_ptr</strong> was rejected not followed by the full committee, <b>counted_ptr</b> was rejected
and surprising transfer-of-ownership semantics were added to <strong>auto-ptr</strong>.</p> and surprising transfer-of-ownership semantics were added to <b>auto_ptr</b>.</p>
<p>Beman Dawes proposed reviving the original semantics under the names <strong>safe_ptr</strong>
and <strong>counted_ptr</strong> at an October, 1998, meeting of Per Andersson, <p>Beman Dawes proposed reviving the original semantics under the names <b>safe_ptr</b>
and <b>counted_ptr</b> at an October, 1998, meeting of Per Andersson,
Matt Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar Matt Austern, Greg Colvin, Sean Corfield, Pete Becker, Nico Josuttis, Dietmar
K<EFBFBD>hl, Nathan Myers, Chichiang Wan and Judy Ward.&nbsp; During the discussion, K<EFBFBD>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 the four class names were finalized, it was decided that there was no need to
exactly follow the <strong>std::auto_ptr</strong> interface, and various exactly follow the <b>std::auto_ptr</b> interface, and various
function signatures and semantics were finalized.</p> function signatures and semantics were finalized.</p>
<p>Over the next three months, several implementations were considered for <strong>shared_ptr</strong>,
<p>Over the next three months, several implementations were considered for <b>shared_ptr</b>,
and discussed on the <a href="http://www.boost.org">boost.org</a> mailing and discussed on the <a href="http://www.boost.org">boost.org</a> mailing
list.&nbsp; The implementation questions revolved around the reference count list. The implementation questions revolved around the reference count
which must be kept, either attached to the pointed to object, or detached which must be kept, either attached to the pointed to object, or detached
elsewhere. Each of those variants have themselves two major variants: elsewhere. Each of those variants have themselves two major variants:
<ul> <ul>
<li>Direct detached: the shared_ptr contains a pointer to the object, and a <li>Direct detached: the shared_ptr contains a pointer to the object, and a
pointer to the count.</li> pointer to the count.</li>
@ -129,22 +178,29 @@ elsewhere. Each of those variants have themselves two major variants:
<li>Embedded attached: the count is a member of the object pointed to.</li> <li>Embedded attached: the count is a member of the object pointed to.</li>
<li>Placement attached: the count is attached via operator new manipulations.</li> <li>Placement attached: the count is attached via operator new manipulations.</li>
</ul> </ul>
<p>Each implementation technique has advantages and disadvantages.&nbsp; We went
<p>Each implementation technique has advantages and disadvantages. We went
so far as to run various timings of the direct and indirect approaches, and 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 found that at least on Intel Pentium chips there was very little measurable
difference.&nbsp; Kevlin Henney provided a paper he wrote on &quot;Counted Body difference. Kevlin Henney provided a paper he wrote on &quot;Counted Body
Techniques.&quot;&nbsp; Dietmar K<>hl suggested an elegant partial template Techniques.&quot; Dietmar K<>hl suggested an elegant partial template
specialization technique to allow users to choose which implementation they specialization technique to allow users to choose which implementation they
preferred, and that was also experimented with.</p> preferred, and that was also experimented with.</p>
<p>But Greg Colvin and Jerry Schwarz argued that &quot;parameterization will <p>But Greg Colvin and Jerry Schwarz argued that &quot;parameterization will
discourage users&quot;, and in the end we choose to supply only the direct discourage users&quot;, and in the end we choose to supply only the direct
implementation.</p> implementation.</p>
<p>See the Revision History section of the header for further contributors.</p> <p>See the Revision History section of the header for further contributors.</p>
<hr> <hr>
<p>Revised&nbsp; <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan
-->24 May 2001<!--webbot bot="Timestamp" endspan i-checksum="15110" <p>Revised <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan
-->1 February 2002<!--webbot bot="Timestamp" endspan i-checksum="15110"
--></p> --></p>
<p><EFBFBD> Copyright Greg Colvin and Beman Dawes 1999. Permission to copy, use,
<p>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 modify, sell and distribute this document is granted provided this copyright
notice appears in all copies. This document is provided &quot;as is&quot; notice appears in all copies. This document is provided &quot;as is&quot;
without express or implied warranty, and with no claim as to its suitability for without express or implied warranty, and with no claim as to its suitability for

View File

@ -13,13 +13,23 @@
// 20 Jul 99 header name changed to .hpp // 20 Jul 99 header name changed to .hpp
// 20 Apr 99 additional error tests added. // 20 Apr 99 additional error tests added.
#include <boost/scoped_ptr.hpp>
#include <boost/scoped_array.hpp>
#include <boost/shared_ptr.hpp>
#include <boost/shared_array.hpp>
#define BOOST_INCLUDE_MAIN #define BOOST_INCLUDE_MAIN
#include <boost/test/test_tools.hpp> #include <boost/test/test_tools.hpp>
#include <boost/smart_ptr.hpp>
#include <cstring> #include <cstring>
#include <iostream> #include <iostream>
#include <set> #include <set>
bool boost_error(char const *, char const *, char const *, long)
{
return true; // fail with assert()
}
class Incomplete; class Incomplete;
Incomplete * get_ptr( boost::shared_ptr<Incomplete>& incomplete ) Incomplete * get_ptr( boost::shared_ptr<Incomplete>& incomplete )
@ -48,7 +58,7 @@ class UDT {
explicit UDT( long value=0 ) : value_(value) { ++UDT_use_count; } explicit UDT( long value=0 ) : value_(value) { ++UDT_use_count; }
~UDT() { ~UDT() {
--UDT_use_count; --UDT_use_count;
cout << "UDT with value " << value_ << " being destroyed" << endl; cout << "UDT with value " << value_ << " being destroyed\n";
} }
long value() const { return value_; } long value() const { return value_; }
void value( long v ) { value_ = v;; } void value( long v ) { value_ = v;; }
@ -71,7 +81,7 @@ Incomplete * check_incomplete( shared_ptr<Incomplete>& incomplete,
shared_ptr<Incomplete>& i2 ) shared_ptr<Incomplete>& i2 )
{ {
incomplete.swap(i2); incomplete.swap(i2);
cout << incomplete.use_count() << " " << incomplete.unique() << endl; cout << incomplete.use_count() << ' ' << incomplete.unique() << '\n';
return incomplete.get(); return incomplete.get();
} }
// main --------------------------------------------------------------------// // main --------------------------------------------------------------------//
@ -186,12 +196,10 @@ int test_main( int, char ** ) {
BOOST_TEST( *cp4 == 87654 ); BOOST_TEST( *cp4 == 87654 );
BOOST_TEST( cp2.get() == 0 ); BOOST_TEST( cp2.get() == 0 );
#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
set< shared_ptr<int> > scp; set< shared_ptr<int> > scp;
scp.insert(cp4); scp.insert(cp4);
BOOST_TEST( scp.find(cp4) != scp.end() ); BOOST_TEST( scp.find(cp4) != scp.end() );
BOOST_TEST( scp.find(cp4) == scp.find( shared_ptr<int>(cp4) ) ); BOOST_TEST( scp.find(cp4) == scp.find( shared_ptr<int>(cp4) ) );
#endif
// test shared_array with a built-in type // test shared_array with a built-in type
char * cap = new char [ 100 ]; char * cap = new char [ 100 ];
@ -232,12 +240,10 @@ int test_main( int, char ** ) {
BOOST_TEST( strcmp( ca4.get(), "Not dog with mustard and relish" ) == 0 ); BOOST_TEST( strcmp( ca4.get(), "Not dog with mustard and relish" ) == 0 );
BOOST_TEST( ca3.get() == 0 ); BOOST_TEST( ca3.get() == 0 );
#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
set< shared_array<char> > sca; set< shared_array<char> > sca;
sca.insert(ca4); sca.insert(ca4);
BOOST_TEST( sca.find(ca4) != sca.end() ); BOOST_TEST( sca.find(ca4) != sca.end() );
BOOST_TEST( sca.find(ca4) == sca.find( shared_array<char>(ca4) ) ); BOOST_TEST( sca.find(ca4) == sca.find( shared_array<char>(ca4) ) );
#endif
// test shared_array with user defined type // test shared_array with user defined type
shared_array<UDT> udta ( new UDT[3] ); shared_array<UDT> udta ( new UDT[3] );
@ -280,7 +286,7 @@ int test_main( int, char ** ) {
BOOST_TEST( sup.use_count() == 2 ); BOOST_TEST( sup.use_count() == 2 );
BOOST_TEST( sup2.use_count() == 2 ); BOOST_TEST( sup2.use_count() == 2 );
cout << "OK" << endl; cout << "OK\n";
new char[12345]; // deliberate memory leak to verify leaks detected new char[12345]; // deliberate memory leak to verify leaks detected

View File

@ -1,295 +0,0 @@
// 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 <boost/scoped_ptr.hpp>
#include <boost/scoped_array.hpp>
#include <boost/shared_ptr.hpp>
#include <boost/shared_array.hpp>
#define BOOST_INCLUDE_MAIN
#include <boost/test/test_tools.hpp>
#include <cstring>
#include <iostream>
#include <set>
bool boost_error(char const *, char const *, char const *, long)
{
return true; // fail with assert()
}
class Incomplete;
Incomplete * get_ptr( boost::shared_ptr<Incomplete>& incomplete )
{
return incomplete.get();
}
using namespace std;
using boost::scoped_ptr;
using boost::scoped_array;
using boost::shared_ptr;
using boost::shared_array;
template<typename T>
void ck( const T* v1, T v2 ) { BOOST_TEST( *v1 == v2 ); }
namespace {
int UDT_use_count; // independent of pointer maintained counts
}
// user defined type -------------------------------------------------------//
class UDT {
long value_;
public:
explicit UDT( long value=0 ) : value_(value) { ++UDT_use_count; }
~UDT() {
--UDT_use_count;
cout << "UDT with value " << value_ << " being destroyed" << endl;
}
long value() const { return value_; }
void value( long v ) { value_ = v;; }
}; // UDT
// tests on incomplete types -----------------------------------------------//
// Certain smart pointer operations are specified to work on incomplete types,
// and some uses depend upon this feature. These tests verify compilation
// only - the functions aren't actually invoked.
class Incomplete;
Incomplete * check_incomplete( scoped_ptr<Incomplete>& incomplete )
{
return incomplete.get();
}
Incomplete * check_incomplete( shared_ptr<Incomplete>& incomplete,
shared_ptr<Incomplete>& i2 )
{
incomplete.swap(i2);
cout << incomplete.use_count() << " " << incomplete.unique() << endl;
return incomplete.get();
}
// main --------------------------------------------------------------------//
// This isn't a very systematic test; it just hits some of the basics.
int test_main( int, char ** ) {
BOOST_TEST( UDT_use_count == 0 ); // reality check
// test scoped_ptr with a built-in type
long * lp = new long;
scoped_ptr<long> sp ( lp );
BOOST_TEST( sp.get() == lp );
BOOST_TEST( lp == sp.get() );
BOOST_TEST( &*sp == lp );
*sp = 1234568901L;
BOOST_TEST( *sp == 1234568901L );
BOOST_TEST( *lp == 1234568901L );
ck( static_cast<long*>(sp.get()), 1234568901L );
ck( lp, *sp );
sp.reset();
BOOST_TEST( sp.get() == 0 );
// test scoped_ptr with a user defined type
scoped_ptr<UDT> udt_sp ( new UDT( 999888777 ) );
BOOST_TEST( udt_sp->value() == 999888777 );
udt_sp.reset();
udt_sp.reset( new UDT( 111222333 ) );
BOOST_TEST( udt_sp->value() == 111222333 );
udt_sp.reset( new UDT( 333222111 ) );
BOOST_TEST( udt_sp->value() == 333222111 );
// test scoped_array with a build-in type
char * sap = new char [ 100 ];
scoped_array<char> sa ( sap );
BOOST_TEST( sa.get() == sap );
BOOST_TEST( sap == sa.get() );
strcpy( sa.get(), "Hot Dog with mustard and relish" );
BOOST_TEST( strcmp( sa.get(), "Hot Dog with mustard and relish" ) == 0 );
BOOST_TEST( strcmp( sap, "Hot Dog with mustard and relish" ) == 0 );
BOOST_TEST( sa[0] == 'H' );
BOOST_TEST( sa[30] == 'h' );
sa[0] = 'N';
sa[4] = 'd';
BOOST_TEST( strcmp( sap, "Not dog with mustard and relish" ) == 0 );
sa.reset();
BOOST_TEST( sa.get() == 0 );
// test shared_ptr with a built-in type
int * ip = new int;
shared_ptr<int> cp ( ip );
BOOST_TEST( ip == cp.get() );
BOOST_TEST( cp.use_count() == 1 );
*cp = 54321;
BOOST_TEST( *cp == 54321 );
BOOST_TEST( *ip == 54321 );
ck( static_cast<int*>(cp.get()), 54321 );
ck( static_cast<int*>(ip), *cp );
shared_ptr<int> cp2 ( cp );
BOOST_TEST( ip == cp2.get() );
BOOST_TEST( cp.use_count() == 2 );
BOOST_TEST( cp2.use_count() == 2 );
BOOST_TEST( *cp == 54321 );
BOOST_TEST( *cp2 == 54321 );
ck( static_cast<int*>(cp2.get()), 54321 );
ck( static_cast<int*>(ip), *cp2 );
shared_ptr<int> cp3 ( cp );
BOOST_TEST( cp.use_count() == 3 );
BOOST_TEST( cp2.use_count() == 3 );
BOOST_TEST( cp3.use_count() == 3 );
cp.reset();
BOOST_TEST( cp2.use_count() == 2 );
BOOST_TEST( cp3.use_count() == 2 );
BOOST_TEST( cp.use_count() == 1 );
cp.reset( new int );
*cp = 98765;
BOOST_TEST( *cp == 98765 );
*cp3 = 87654;
BOOST_TEST( *cp3 == 87654 );
BOOST_TEST( *cp2 == 87654 );
cp.swap( cp3 );
BOOST_TEST( *cp == 87654 );
BOOST_TEST( *cp2 == 87654 );
BOOST_TEST( *cp3 == 98765 );
cp.swap( cp3 );
BOOST_TEST( *cp == 98765 );
BOOST_TEST( *cp2 == 87654 );
BOOST_TEST( *cp3 == 87654 );
cp2 = cp2;
BOOST_TEST( cp2.use_count() == 2 );
BOOST_TEST( *cp2 == 87654 );
cp = cp2;
BOOST_TEST( cp2.use_count() == 3 );
BOOST_TEST( *cp2 == 87654 );
BOOST_TEST( cp.use_count() == 3 );
BOOST_TEST( *cp == 87654 );
shared_ptr<int> cp4;
swap( cp2, cp4 );
BOOST_TEST( cp4.use_count() == 3 );
BOOST_TEST( *cp4 == 87654 );
BOOST_TEST( cp2.get() == 0 );
set< shared_ptr<int> > scp;
scp.insert(cp4);
BOOST_TEST( scp.find(cp4) != scp.end() );
BOOST_TEST( scp.find(cp4) == scp.find( shared_ptr<int>(cp4) ) );
// test shared_array with a built-in type
char * cap = new char [ 100 ];
shared_array<char> ca ( cap );
BOOST_TEST( ca.get() == cap );
BOOST_TEST( cap == ca.get() );
BOOST_TEST( &ca[0] == cap );
strcpy( ca.get(), "Hot Dog with mustard and relish" );
BOOST_TEST( strcmp( ca.get(), "Hot Dog with mustard and relish" ) == 0 );
BOOST_TEST( strcmp( cap, "Hot Dog with mustard and relish" ) == 0 );
BOOST_TEST( ca[0] == 'H' );
BOOST_TEST( ca[30] == 'h' );
shared_array<char> ca2 ( ca );
shared_array<char> ca3 ( ca2 );
ca[0] = 'N';
ca[4] = 'd';
BOOST_TEST( strcmp( ca.get(), "Not dog with mustard and relish" ) == 0 );
BOOST_TEST( strcmp( ca2.get(), "Not dog with mustard and relish" ) == 0 );
BOOST_TEST( strcmp( ca3.get(), "Not dog with mustard and relish" ) == 0 );
BOOST_TEST( ca.use_count() == 3 );
BOOST_TEST( ca2.use_count() == 3 );
BOOST_TEST( ca3.use_count() == 3 );
ca2.reset();
BOOST_TEST( ca.use_count() == 2 );
BOOST_TEST( ca3.use_count() == 2 );
BOOST_TEST( ca2.use_count() == 1 );
ca.reset();
BOOST_TEST( ca.get() == 0 );
shared_array<char> ca4;
swap( ca3, ca4 );
BOOST_TEST( ca4.use_count() == 1 );
BOOST_TEST( strcmp( ca4.get(), "Not dog with mustard and relish" ) == 0 );
BOOST_TEST( ca3.get() == 0 );
set< shared_array<char> > sca;
sca.insert(ca4);
BOOST_TEST( sca.find(ca4) != sca.end() );
BOOST_TEST( sca.find(ca4) == sca.find( shared_array<char>(ca4) ) );
// test shared_array with user defined type
shared_array<UDT> udta ( new UDT[3] );
udta[0].value( 111 );
udta[1].value( 222 );
udta[2].value( 333 );
shared_array<UDT> udta2 ( udta );
BOOST_TEST( udta[0].value() == 111 );
BOOST_TEST( udta[1].value() == 222 );
BOOST_TEST( udta[2].value() == 333 );
BOOST_TEST( udta2[0].value() == 111 );
BOOST_TEST( udta2[1].value() == 222 );
BOOST_TEST( udta2[2].value() == 333 );
udta2.reset();
BOOST_TEST( udta2.get() == 0 );
BOOST_TEST( udta.use_count() == 1 );
BOOST_TEST( udta2.use_count() == 1 );
BOOST_TEST( UDT_use_count == 4 ); // reality check
// test shared_ptr with a user defined type
UDT * up = new UDT;
shared_ptr<UDT> sup ( up );
BOOST_TEST( up == sup.get() );
BOOST_TEST( sup.use_count() == 1 );
sup->value( 54321 ) ;
BOOST_TEST( sup->value() == 54321 );
BOOST_TEST( up->value() == 54321 );
shared_ptr<UDT> sup2;
sup2 = sup;
BOOST_TEST( sup2->value() == 54321 );
BOOST_TEST( sup.use_count() == 2 );
BOOST_TEST( sup2.use_count() == 2 );
sup2 = sup2;
BOOST_TEST( sup2->value() == 54321 );
BOOST_TEST( sup.use_count() == 2 );
BOOST_TEST( sup2.use_count() == 2 );
cout << "OK" << endl;
new char[12345]; // deliberate memory leak to verify leaks detected
return 0;
} // main

View File

@ -1,13 +1,15 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html> <html>
<head> <head>
<title>boost: smart pointer tests</title> <title>Smart Pointer Timings</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<!-- </head>
-->
<body bgcolor="#FFFFFF"> <body bgcolor="#FFFFFF">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="center" WIDTH="277" HEIGHT="86">Smart <h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" WIDTH="277" HEIGHT="86">Smart Pointer Timings</h1>
Pointers Timings </h1>
<p>In late January 2000, Mark Borgerding put forward a suggestion to boost for <p>In late January 2000, Mark Borgerding put forward a suggestion to boost for
a new design of smart pointer whereby an intrusive doubly linked list is used a new design of smart pointer whereby an intrusive doubly linked list is used
@ -19,9 +21,10 @@ Pointers Timings </h1>
mailing list and the tests which this page describes were performed to provide mailing list and the tests which this page describes were performed to provide
a guide for current and future investigations into smart pointer implementation a guide for current and future investigations into smart pointer implementation
strategies.</p> strategies.</p>
<p>Thanks are due to <a href="../../people/dave_abrahams.htm"> Dave Abrahams</a>, <p>Thanks are due to <a href="../../people/dave_abrahams.htm">Dave Abrahams</a>,
<a href="../../people/gavin_collings.htm"> Gavin Collings</a>, <a href="../../people/greg_colvin.htm"> Greg Colvin</a> and <a href="../../people/gavin_collings.htm">Gavin Collings</a>,
<a href="../../people/beman_dawes.html"> Beman Dawes</a> <a href="../../people/greg_colvin.htm">Greg Colvin</a> and
<a href="../../people/beman_dawes.html">Beman Dawes</a>
for test code and trial implementations, the final version of which can be found for test code and trial implementations, the final version of which can be found
in .zip format <a href="smarttest.zip">here</a>.</p> in .zip format <a href="smarttest.zip">here</a>.</p>
<h2>Description</h2> <h2>Description</h2>
@ -75,7 +78,7 @@ Pointers Timings </h1>
</tr> </tr>
<tr> <tr>
<td width="20">&nbsp; </td> <td width="20">&nbsp; </td>
<td><img src="msvcspeed.gif" width="560" height="355"></td> <td><img src="msvcspeed.gif" width="560" height="355" alt="MSVC speed graph"></td>
<td width="20">&nbsp;</td> <td width="20">&nbsp;</td>
</tr> </tr>
<tr> <tr>
@ -85,7 +88,7 @@ Pointers Timings </h1>
</tr> </tr>
<tr> <tr>
<td>&nbsp;</td> <td>&nbsp;</td>
<td><img src="gccspeed.gif" width="560" height="355"></td> <td><img src="gccspeed.gif" width="560" height="355" alt="GCC speed graph"></td>
<td>&nbsp;</td> <td>&nbsp;</td>
</tr> </tr>
<tr> <tr>
@ -530,7 +533,7 @@ Pointers Timings </h1>
spreads its information as in the case of linked pointer.</li> spreads its information as in the case of linked pointer.</li>
</ul> </ul>
<hr> <hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %b %Y" startspan -->19 Aug 2001<!--webbot bot="Timestamp" endspan i-checksum="14767" --> <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->19 August 2001<!--webbot bot="Timestamp" endspan i-checksum="14767" -->
</p> </p>
<p><EFBFBD> Copyright Gavin Collings 2000. Permission to copy, use, modify, sell <p><EFBFBD> Copyright Gavin Collings 2000. Permission to copy, use, modify, sell
and distribute this document is granted provided this copyright notice appears in all and distribute this document is granted provided this copyright notice appears in all

233
weak_ptr.htm Normal file
View File

@ -0,0 +1,233 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>weak_ptr</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align="middle" width="277" height="86">weak_ptr class template</h1>
<p><a href="#Introduction">Introduction</a><br>
<a href="#Synopsis">Synopsis</a><br>
<a href="#Members">Members</a><br>
<a href="#functions">Free Functions</a><br>
<a href="#example">Example</a><br>
<a href="#Handle/Body">Handle/Body Idiom</a><br>
<a href="#FAQ">Frequently Asked Questions</a><br>
<a href="smarttests.htm">Smart Pointer Timings</a></p>
<h2><a name="Introduction">Introduction</a></h2>
<p>The <b>weak_ptr</b> class template stores a pointer to an
object that's already managed by a <b>shared_ptr</b>. When the
object last <b>shared_ptr</b> to the object goes away and the object
is deleted, all <b>weak_ptr</b> objects have their stored pointers
set to 0.</p>
<p>Every <b>weak_ptr</b> meets the <b>CopyConstructible</b>
and <b>Assignable</b> requirements of the C++ Standard Library, and so
can be used in standard library containers. Comparison operators
are supplied so that <b>weak_ptr</b> works with
the standard library's associative containers.</p>
<p>The class template is parameterized on <b>T</b>, the type of the object
pointed to. <b>T</b> must meet the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h2><a name="Synopsis">Synopsis</a></h2>
<pre>namespace boost {
template&lt;typename T&gt; class weak_ptr {
public:
typedef T <a href="#element_type">element_type</a>;
explicit <a href="#constructors">weak_ptr</a>();
template&lt;typename Y&gt; <a href="#constructors">weak_ptr</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws
<a href="#destructor">~weak_ptr</a>(); // never throws
<a href="#constructors">weak_ptr</a>(weak_ptr const &amp; r); // never throws
template&lt;typename Y&gt; <a href="#constructors">weak_ptr</a>(weak_ptr&lt;Y&gt; const &amp; r); // never throws
weak_ptr &amp; <a href="#assignment">operator=</a>(weak_ptr const &amp; r); // never throws
template&lt;typename Y&gt; weak_ptr &amp; <a href="#assignment">operator=</a>(weak_ptr&lt;Y&gt; const &amp; r); // never throws
template&lt;typename Y&gt; weak_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws
void <a href="#reset">reset</a>(); // never throws
T &amp; <a href="#indirection">operator*</a>() const; // never throws
T * <a href="#indirection">operator-&gt;</a>() const; // never throws
T * <a href="#get">get</a>() const; // never throws
long <a href="#use_count">use_count</a>() const; // never throws
void <a href="#swap">swap</a>(weak_ptr&lt;T&gt; &amp; b); // never throws
};
template&lt;typename T, typename U&gt;
bool <a href="#operator==">operator==</a>(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b); // never throws
template&lt;typename T, typename U&gt;
bool <a href="#operator!=">operator!=</a>(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b); // never throws
template&lt;typename T, typename U&gt;
bool <a href="#operator&lt;">operator&lt;</a>(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b); // never throws
template&lt;typename T&gt; void <a href="#free-swap">swap</a>(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b); // never throws
template&lt;typename T, typename U&gt;
weak_ptr&lt;T&gt <a href="#shared_static_cast">shared_static_cast</a>(weak_ptr&lt;U&gt; const &amp; r); // never throws
template&lt;typename T, typename U&gt;
weak_ptr&lt;T&gt <a href="#shared_dynamic_cast">shared_dynamic_cast</a>(weak_ptr&lt;U&gt; const &amp; r);
}</pre>
<h2><a name="Members">Members</a></h2>
<h3><a name="element_type">element_type</a></h3>
<pre>typedef T element_type;</pre>
<p>Provides the type of the stored pointer.</p>
<h3><a name="constructors">constructors</a></h3>
<pre>explicit weak_ptr();</pre>
<p>Constructs a <b>weak_ptr</b>, with 0 as its stored pointer.
The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
If an exception is thrown, the constructor has no effect.</p>
<pre>template&lt;typename Y&gt; weak_ptr</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws</pre>
<p>Constructs a <b>weak_ptr</b>, as if by storing a copy of the pointer stored in <b>r</b>.
Afterwards, the <a href="#use_count">use count</a> for all copies is unchanged.
When the last <b>shared_ptr</b> is destroyed, the use count and stored pointer become 0.
The only exception which may be thrown by this constructor is <b>std::bad_alloc</b>.
If an exception is thrown, the constructor has no effect.</p>
<pre>weak_ptr(weak_ptr const &amp; r); // never throws
template&lt;typename Y&gt; weak_ptr(weak_ptr&lt;Y&gt; const &amp; r); // never throws</pre>
<p>Constructs a <b>weak_ptr</b>, as if by storing a copy of the
pointer stored in <b>r</b>.</p>
<h3><a name="destructor">destructor</a></h3>
<pre>~weak_ptr(); // never throws</pre>
<p>Destroys this <b>weak_ptr</b> but has no effect on the object its stored pointer points to.
<b>T</b> need not be a complete type.
See the smart pointer <a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="operator=">assignment</a></h3>
<pre>weak_ptr &amp; <a href="#assignment">operator=</a>(weak_ptr const &amp; r); // never throws
template&lt;typename Y&gt; weak_ptr &amp; <a href="#assignment">operator=</a>(weak_ptr&lt;Y&gt; const &amp; r); // never throws
template&lt;typename Y&gt; weak_ptr &amp; <a href="#assignment">operator=</a>(shared_ptr&lt;Y&gt; const &amp; r); // never throws</pre>
<p>Constructs a new <b>weak_ptr</b> as described <a href="#constructors">above</a>,
then replaces this <b>weak_ptr</b> with the new one, destroying the replaced object.</p>
<h3><a name="reset">reset</a></h3>
<pre>void reset();</pre>
<p>Constructs a new <b>weak_ptr</b> as described <a href="#constructors">above</a>,
then replaces this <b>weak_ptr</b> with the new one, destroying the replaced object.
The only exception which may be thrown is <b>std::bad_alloc</b>. If
an exception is thrown, the <b>reset</b> has no effect.</p>
<h3><a name="indirection">indirection</a></h3>
<pre>T &amp; operator*() const; // never throws</pre>
<p>Returns a reference to the object pointed to by the stored pointer.
Behavior is undefined if the stored pointer is 0.
Note that the stored pointer becomes 0 if all <b>shared_ptr</b> objects for that
pointer are destroyed.</p>
<pre>T * operator-&gt;() const; // never throws</pre>
<p>Returns the stored pointer.
Behavior is undefined if the stored pointer is 0.
Note that the stored pointer becomes 0 if all <b>shared_ptr</b> objects for that
pointer are destroyed.</p>
<h3><a name="get">get</a></h3>
<pre>T * get() const; // never throws</pre>
<p>Returns the stored pointer.
Note that the stored pointer becomes 0 if all <b>shared_ptr</b> objects for that
pointer are destroyed.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h3><a name="use_count">use_count</a></h3>
<pre>long use_count() const; // never throws</pre>
<p>Returns the number of <b>shared_ptr</b> objects sharing ownership of the
stored pointer.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>Because <b>use_count</b> is not necessarily efficient to implement for
implementations of <b>weak_ptr</b> 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 <b>get</b> should be used for
production code.</p>
<h3><a name="swap">swap</a></h3>
<pre>void swap(weak_ptr &amp; b); // never throws</pre>
<p>Exchanges the contents of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<h2><a name="functions">Free Functions</a></h2>
<h3><a name="comparison">comparison</a></h3>
<pre>template&lt;typename T, typename U&gt;
bool <a href="#operator==">operator==</a>(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b); // never throws
template&lt;typename T, typename U&gt;
bool <a href="#operator!=">operator!=</a>(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b); // never throws
template&lt;typename T, typename U&gt;
bool <a href="#operator&lt;">operator&lt;</a>(weak_ptr&lt;T&gt; const &amp; a, weak_ptr&lt;U&gt; const &amp; b); // never throws</pre>
<p>Compares the stored pointers of the two smart pointers.
<b>T</b> need not be a complete type.
See the smart pointer
<a href="smart_ptr.htm#Common requirements">common requirements</a>.</p>
<p>The <b>operator&lt;</b> overload is provided to define an ordering so that <b>weak_ptr</b>
objects can be used in associative containers such as <b>std::map</b>.
The implementation uses std::less&lt;T*&gt; 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&lt;&gt; on pointers is well-defined (20.3.3 [lib.comparisons]
paragraph 8).</p>
<h3><a name="free-swap">swap</a></h3>
<pre>template&lt;typename T&gt;
void swap(weak_ptr&lt;T&gt; &amp; a, weak_ptr&lt;T&gt; &amp; b) // never throws</pre>
<p>Equivalent to <b>a.swap(b)</b>. Matches the interface of <b>std::swap</b>.
Provided as an aid to generic programming.</p>
<h3><a name="shared_static_cast">shared_static_cast</a></h3>
<pre>template&lt;typename T, typename U&gt;
weak_ptr&lt;T&gt <a href="#shared_static_cast">shared_static_cast</a>(weak_ptr&lt;U&gt; const &amp; r); // never throws</pre>
<p>Perform a <b>static_cast</b> on the stored pointer, returning another <b>weak_ptr</b>.
The resulting smart pointer will share its use count with the original pointer.</p>
<h3><a name="shared_dynamic_cast">shared_dynamic_cast</a></h3>
<pre>template&lt;typename T, typename U&gt;
weak_ptr&lt;T&gt <a href="#shared_dynamic_cast">shared_dynamic_cast</a>(weak_ptr&lt;U&gt; const &amp; r);</pre>
<p>Perform a <b>dynamic_cast</b> on the stored pointer, returning another <b>weak_ptr</b>.
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 <b>std::bad_alloc</b>, which may be thrown during the
construction of the new <b>weak_ptr</b> if the result of the cast is 0. If an exception is thrown, the
cast has no effect.</p>
<hr>
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan -->1 February 2002<!--webbot bot="Timestamp" i-checksum="38439" endspan --></p>
<p>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 &quot;as is&quot; without express or implied warranty,
and with no claim as to its suitability for any purpose.</p>
</body>
</html>