...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
Introduction
Synopsis
Members
Free Functions
The intrusive_ptr class template stores a pointer to an object with an embedded reference count. Every new intrusive_ptr instance increments the reference count by using an unqualified call to the function intrusive_ptr_add_ref, passing it the pointer as an argument. Similarly, when an intrusive_ptr is destroyed, it calls intrusive_ptr_release; this function is responsible for destroying the object when its reference count drops to zero. The user is expected to provide suitable definitions of these two functions. On compilers that support argument-dependent lookup, intrusive_ptr_add_ref and intrusive_ptr_release should be defined in the namespace that corresponds to their parameter; otherwise, the definitions need to go in namespace boost.
The class template is parameterized on T, the type of the object pointed
to. intrusive_ptr
The main reasons to use intrusive_ptr are:
As a general rule, if it isn't obvious whether intrusive_ptr better fits your needs than shared_ptr, try a shared_ptr-based design first.
namespace boost { templateclass intrusive_ptr { public: typedef T element_type; intrusive_ptr(); // never throws intrusive_ptr(T * p, bool add_ref = true); intrusive_ptr(intrusive_ptr const & r); template intrusive_ptr(intrusive_ptr const & r); ~intrusive_ptr(); intrusive_ptr & operator=(intrusive_ptr const & r); template intrusive_ptr & operator=(intrusive_ptr const & r); intrusive_ptr & operator=(T * r); void reset(); void reset(T * r); T & operator*() const; // never throws T * operator->() const; // never throws T * get() const; // never throws operator unspecified-bool-type() const; // never throws void swap(intrusive_ptr & b); // never throws }; template bool operator==(intrusive_ptr const & a, intrusive_ptr const & b); // never throws template bool operator!=(intrusive_ptr const & a, intrusive_ptr const & b); // never throws template bool operator==(intrusive_ptr const & a, T * b); // never throws template bool operator!=(intrusive_ptr const & a, T * b); // never throws template bool operator==(T * a, intrusive_ptr const & b); // never throws template bool operator!=(T * a, intrusive_ptr const & b); // never throws template bool operator<(intrusive_ptr const & a, intrusive_ptr const & b); // never throws template void swap(intrusive_ptr & a, intrusive_ptr & b); // never throws template T * get_pointer(intrusive_ptr const & p); // never throws template intrusive_ptr static_pointer_cast(intrusive_ptr const & r); // never throws template intrusive_ptr const_pointer_cast(intrusive_ptr const & r); // never throws template intrusive_ptr dynamic_pointer_cast(intrusive_ptr const & r); // never throws template std::basic_ostream & operator<< (std::basic_ostream & os, intrusive_ptr const & p); }
typedef T element_type;
Provides the type of the template parameter T.
intrusive_ptr(); // never throws
Postconditions:
get() == 0
.Throws: nothing.
intrusive_ptr(T * p, bool add_ref = true);
Effects:
if(p != 0 && add_ref) intrusive_ptr_add_ref(p);
.Postconditions:
get() == p
.
intrusive_ptr(intrusive_ptr const & r); templateintrusive_ptr(intrusive_ptr const & r);
Effects:
if(r.get() != 0) intrusive_ptr_add_ref(r.get());
.Postconditions:
get() == r.get()
.
~intrusive_ptr();
Effects:
if(get() != 0) intrusive_ptr_release(get());
.
intrusive_ptr & operator=(intrusive_ptr const & r); templateintrusive_ptr & operator=(intrusive_ptr const & r); intrusive_ptr & operator=(T * r);
Effects: Equivalent to
intrusive_ptr(r).swap(*this)
.Returns:
*this
.
void reset();
Effects: Equivalent to
intrusive_ptr().swap(*this)
.
void reset(T * r);
Effects: Equivalent to
intrusive_ptr(r).swap(*this)
.
T & operator*() const; // never throws
Requirements:
get() != 0
.Returns:
*get()
.Throws: nothing.
T * operator->() const; // never throws
Requirements:
get() != 0
.Returns:
get()
.Throws: nothing.
T * get() const; // never throws
Returns: the stored pointer.
Throws: nothing.
operator unspecified-bool-type () const; // never throws
Returns: an unspecified value that, when used in boolean contexts, is equivalent to
get() != 0
.Throws: nothing.
Notes: This conversion operator allows intrusive_ptr objects to be used in boolean contexts, like
if (p && p->valid()) {}
. The actual target type is typically a pointer to a member function, avoiding many of the implicit conversion pitfalls.
void swap(intrusive_ptr & b); // never throws
Effects: Exchanges the contents of the two smart pointers.
Throws: nothing.
templatebool operator==(intrusive_ptr const & a, intrusive_ptr const & b); // never throws
Returns:
a.get() == b.get()
.Throws: nothing.
templatebool operator!=(intrusive_ptr const & a, intrusive_ptr const & b); // never throws
Returns:
a.get() != b.get()
.Throws: nothing.
templatebool operator==(intrusive_ptr const & a, U * b); // never throws
Returns:
a.get() == b
.Throws: nothing.
templatebool operator!=(intrusive_ptr const & a, U * b); // never throws
Returns:
a.get() != b
.Throws: nothing.
templatebool operator==(T * a, intrusive_ptr const & b); // never throws
Returns:
a == b.get()
.Throws: nothing.
templatebool operator!=(T * a, intrusive_ptr const & b); // never throws
Returns:
a != b.get()
.Throws: nothing.
templatebool operator<(intrusive_ptr const & a, intrusive_ptr const & b); // never throws
Returns:
std::less
.()(a.get(), b.get()) Throws: nothing.
Notes: Allows intrusive_ptr objects to be used as keys in associative containers.
templatevoid swap(intrusive_ptr & a, intrusive_ptr & b); // never throws
Effects: Equivalent to
a.swap(b)
.Throws: nothing.
Notes: Matches the interface of std::swap. Provided as an aid to generic programming.
templateT * get_pointer(intrusive_ptr const & p); // never throws
Returns:
p.get()
.Throws: nothing.
Notes: Provided as an aid to generic programming. Used by mem_fn.
templateintrusive_ptr static_pointer_cast(intrusive_ptr const & r); // never throws
Returns:
intrusive_ptr
.(static_cast (r.get())) Throws: nothing.
templateintrusive_ptr const_pointer_cast(intrusive_ptr const & r); // never throws
Returns:
intrusive_ptr
.(const_cast (r.get())) Throws: nothing.
templateintrusive_ptr dynamic_pointer_cast(intrusive_ptr const & r);
Returns:
intrusive_ptr
.(dynamic_cast (r.get())) Throws: nothing.
templatestd::basic_ostream & operator<< (std::basic_ostream & os, intrusive_ptr const & p);
Effects:
os << p.get();
.Returns:
os
.
$Date: 2008-07-12 07:37:16 -0400 (Sat, 12 Jul 2008) $
Copyright © 2003-2005 Peter Dimov. Distributed under the Boost Software License, Version 1.0. See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt.