| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title>intrusive_ptr</title> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| </head> |
| <body text="#000000" bgColor="#ffffff"> |
| <h1><A href="../../index.htm"><IMG height="86" alt="boost.png (6897 bytes)" src="../../boost.png" width="277" align="middle" |
| border="0"></A>intrusive_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> |
| </p> |
| <h2><a name="Introduction">Introduction</a></h2> |
| <p>The <b>intrusive_ptr</b> class template stores a pointer to an object with an |
| embedded reference count. Every new <b>intrusive_ptr</b> instance increments |
| the reference count by using an unqualified call to the function <STRONG>intrusive_ptr_add_ref</STRONG>, |
| passing it the pointer as an argument. Similarly, when an <STRONG>intrusive_ptr</STRONG> |
| is destroyed, it calls <STRONG>intrusive_ptr_release</STRONG>; 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, <STRONG>intrusive_ptr_add_ref</STRONG> |
| and <STRONG>intrusive_ptr_release</STRONG> should be defined in the namespace |
| that corresponds to their parameter; otherwise, the definitions need to go in |
| namespace <STRONG>boost</STRONG>.</p> |
| <p>The class template is parameterized on <b>T</b>, the type of the object pointed |
| to. <STRONG>intrusive_ptr<T></STRONG> can be implicitly converted to <STRONG>intrusive_ptr<U></STRONG> |
| whenever <STRONG>T*</STRONG> can be implicitly converted to <STRONG>U*</STRONG>.</p> |
| <P>The main reasons to use <STRONG>intrusive_ptr</STRONG> are:</P> |
| <UL> |
| <LI> |
| Some existing frameworks or OSes provide objects with embedded reference |
| counts; |
| <LI> |
| The memory footprint of <STRONG>intrusive_ptr</STRONG> |
| is the same as the corresponding raw pointer; |
| <LI> |
| <STRONG>intrusive_ptr<T></STRONG> can be constructed from an arbitrary |
| raw pointer of type <STRONG>T *</STRONG>.</LI></UL> |
| <P>As a general rule, if it isn't obvious whether <STRONG>intrusive_ptr</STRONG> better |
| fits your needs than <STRONG>shared_ptr</STRONG>, try a <STRONG>shared_ptr</STRONG>-based |
| design first.</P> |
| <h2><a name="Synopsis">Synopsis</a></h2> |
| <pre>namespace boost { |
| |
| template<class T> class intrusive_ptr { |
| |
| public: |
| |
| typedef T <A href="#element_type" >element_type</A>; |
| |
| <A href="#constructors" >intrusive_ptr</A>(); // never throws |
| <A href="#constructors" >intrusive_ptr</A>(T * p, bool add_ref = true); |
| |
| <A href="#constructors" >intrusive_ptr</A>(intrusive_ptr const & r); |
| template<class Y> <A href="#constructors" >intrusive_ptr</A>(intrusive_ptr<Y> const & r); |
| |
| <A href="#destructor" >~intrusive_ptr</A>(); |
| |
| intrusive_ptr & <A href="#assignment" >operator=</A>(intrusive_ptr const & r); |
| template<class Y> intrusive_ptr & <A href="#assignment" >operator=</A>(intrusive_ptr<Y> const & r); |
| intrusive_ptr & <A href="#assignment" >operator=</A>(T * r); |
| |
| void <a href="#reset" >reset</a>(); |
| void <a href="#reset" >reset</a>(T * r); |
| |
| T & <A href="#indirection" >operator*</A>() const; // never throws |
| T * <A href="#indirection" >operator-></A>() const; // never throws |
| T * <A href="#get" >get</A>() const; // never throws |
| |
| operator <A href="#conversions" ><i>unspecified-bool-type</i></A>() const; // never throws |
| |
| void <A href="#swap" >swap</A>(intrusive_ptr & b); // never throws |
| }; |
| |
| template<class T, class U> |
| bool <A href="#comparison" >operator==</A>(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws |
| |
| template<class T, class U> |
| bool <A href="#comparison" >operator!=</A>(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws |
| |
| template<class T> |
| bool <A href="#comparison" >operator==</A>(intrusive_ptr<T> const & a, T * b); // never throws |
| |
| template<class T> |
| bool <A href="#comparison" >operator!=</A>(intrusive_ptr<T> const & a, T * b); // never throws |
| |
| template<class T> |
| bool <A href="#comparison" >operator==</A>(T * a, intrusive_ptr<T> const & b); // never throws |
| |
| template<class T> |
| bool <A href="#comparison" >operator!=</A>(T * a, intrusive_ptr<T> const & b); // never throws |
| |
| template<class T, class U> |
| bool <A href="#comparison" >operator<</A>(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws |
| |
| template<class T> void <A href="#free-swap" >swap</A>(intrusive_ptr<T> & a, intrusive_ptr<T> & b); // never throws |
| |
| template<class T> T * <A href="#get_pointer" >get_pointer</A>(intrusive_ptr<T> const & p); // never throws |
| |
| template<class T, class U> |
| intrusive_ptr<T> <A href="#static_pointer_cast" >static_pointer_cast</A>(intrusive_ptr<U> const & r); // never throws |
| |
| template<class T, class U> |
| intrusive_ptr<T> <A href="#const_pointer_cast" >const_pointer_cast</A>(intrusive_ptr<U> const & r); // never throws |
| |
| template<class T, class U> |
| intrusive_ptr<T> <A href="#dynamic_pointer_cast" >dynamic_pointer_cast</A>(intrusive_ptr<U> const & r); // never throws |
| |
| template<class E, class T, class Y> |
| std::basic_ostream<E, T> & <A href="#insertion-operator" >operator<<</A> (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p); |
| |
| }</pre> |
| <h2><a name="Members">Members</a></h2> |
| <h3><a name="element_type">element_type</a></h3> |
| <pre>typedef T element_type;</pre> |
| <blockquote> |
| <p>Provides the type of the template parameter T.</p> |
| </blockquote> |
| <h3><a name="constructors">constructors</a></h3> |
| <pre>intrusive_ptr(); // never throws</pre> |
| <blockquote> |
| <p><b>Postconditions:</b> <code>get() == 0</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>intrusive_ptr(T * p, bool add_ref = true);</pre> |
| <blockquote> |
| <p><b>Effects:</b> <code>if(p != 0 && add_ref) intrusive_ptr_add_ref(p);</code>.</p> |
| <p><b>Postconditions:</b> <code>get() == p</code>.</p> |
| </blockquote> |
| <pre>intrusive_ptr(intrusive_ptr const & r); |
| template<class Y> intrusive_ptr(intrusive_ptr<Y> const & r);</pre> |
| <blockquote> |
| <p><b>Effects:</b> <code>if(r.get() != 0) intrusive_ptr_add_ref(r.get());</code>.</p> |
| <p><b>Postconditions:</b> <code>get() == r.get()</code>.</p> |
| </blockquote> |
| <h3><a name="destructor">destructor</a></h3> |
| <pre>~intrusive_ptr();</pre> |
| <BLOCKQUOTE> |
| <P><B>Effects:</B> <code>if(get() != 0) intrusive_ptr_release(get());</code>.</P> |
| </BLOCKQUOTE> |
| <H3><a name="assignment">assignment</a></H3> |
| <pre>intrusive_ptr & operator=(intrusive_ptr const & r); |
| template<class Y> intrusive_ptr & operator=(intrusive_ptr<Y> const & r); |
| intrusive_ptr & operator=(T * r);</pre> |
| <BLOCKQUOTE> |
| <P><B>Effects:</B> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</P> |
| <P><B>Returns:</B> <code>*this</code>.</P> |
| </BLOCKQUOTE> |
| <H3><a name="reset">reset</a></H3> |
| <pre>void reset();</pre> |
| <BLOCKQUOTE> |
| <P><B>Effects:</B> Equivalent to <code>intrusive_ptr().swap(*this)</code>.</P> |
| </BLOCKQUOTE> |
| <pre>void reset(T * r);</pre> |
| <BLOCKQUOTE> |
| <P><B>Effects:</B> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</P> |
| </BLOCKQUOTE> |
| <h3><a name="indirection">indirection</a></h3> |
| <pre>T & operator*() const; // never throws</pre> |
| <blockquote> |
| <p><b>Requirements:</b> <code>get() != 0</code>.</p> |
| <p><b>Returns:</b> <code>*get()</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>T * operator->() const; // never throws</pre> |
| <blockquote> |
| <p><b>Requirements:</b> <code>get() != 0</code>.</p> |
| <p><b>Returns:</b> <code>get()</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <h3><a name="get">get</a></h3> |
| <pre>T * get() const; // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> the stored pointer.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <h3><a name="conversions">conversions</a></h3> |
| <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is |
| equivalent to <code>get() != 0</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| <P><B>Notes:</B> This conversion operator allows <b>intrusive_ptr</b> objects to be |
| used in boolean contexts, like <code>if (p && p->valid()) {}</code>. |
| The actual target type is typically a pointer to a member function, avoiding |
| many of the implicit conversion pitfalls.</P> |
| </blockquote> |
| <h3><a name="swap">swap</a></h3> |
| <pre>void swap(intrusive_ptr & b); // never throws</pre> |
| <blockquote> |
| <p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <h2><a name="functions">Free Functions</a></h2> |
| <h3><a name="comparison">comparison</a></h3> |
| <pre>template<class T, class U> |
| bool operator==(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> <code>a.get() == b.get()</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>template<class T, class U> |
| bool operator!=(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> <code>a.get() != b.get()</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>template<class T, class U> |
| bool operator==(intrusive_ptr<T> const & a, U * b); // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> <code>a.get() == b</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>template<class T, class U> |
| bool operator!=(intrusive_ptr<T> const & a, U * b); // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> <code>a.get() != b</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>template<class T, class U> |
| bool operator==(T * a, intrusive_ptr<U> const & b); // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> <code>a == b.get()</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>template<class T, class U> |
| bool operator!=(T * a, intrusive_ptr<U> const & b); // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> <code>a != b.get()</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| </blockquote> |
| <pre>template<class T, class U> |
| bool operator<(intrusive_ptr<T> const & a, intrusive_ptr<U> const & b); // never throws</pre> |
| <blockquote> |
| <p><b>Returns:</b> <code>std::less<T *>()(a.get(), b.get())</code>.</p> |
| <p><b>Throws:</b> nothing.</p> |
| <P><B>Notes:</B> Allows <STRONG>intrusive_ptr</STRONG> objects to be used as keys |
| in associative containers.</P> |
| </blockquote> |
| <h3><a name="free-swap">swap</a></h3> |
| <pre>template<class T> |
| void swap(intrusive_ptr<T> & a, intrusive_ptr<T> & b); // never throws</pre> |
| <BLOCKQUOTE> |
| <P><B>Effects:</B> Equivalent to <code>a.swap(b)</code>.</P> |
| <P><B>Throws:</B> nothing.</P> |
| <P><B>Notes:</B> Matches the interface of <B>std::swap</B>. Provided as an aid to |
| generic programming.</P> |
| </BLOCKQUOTE> |
| <h3><a name="get_pointer">get_pointer</a></h3> |
| <pre>template<class T> |
| T * get_pointer(intrusive_ptr<T> const & p); // never throws</pre> |
| <BLOCKQUOTE> |
| <P><B>Returns:</B> <code>p.get()</code>.</P> |
| <P><B>Throws:</B> nothing.</P> |
| <P><B>Notes:</B> Provided as an aid to generic programming. Used by <A href="../bind/mem_fn.html"> |
| mem_fn</A>.</P> |
| </BLOCKQUOTE> |
| <h3><a name="static_pointer_cast">static_pointer_cast</a></h3> |
| <pre>template<class T, class U> |
| intrusive_ptr<T> static_pointer_cast(intrusive_ptr<U> const & r); // never throws</pre> |
| <BLOCKQUOTE> |
| <P><B>Returns:</B> <code>intrusive_ptr<T>(static_cast<T*>(r.get()))</code>.</P> |
| <P><B>Throws:</B> nothing.</P> |
| </BLOCKQUOTE> |
| <h3><a name="const_pointer_cast">const_pointer_cast</a></h3> |
| <pre>template<class T, class U> |
| intrusive_ptr<T> const_pointer_cast(intrusive_ptr<U> const & r); // never throws</pre> |
| <BLOCKQUOTE> |
| <P><B>Returns:</B> <code>intrusive_ptr<T>(const_cast<T*>(r.get()))</code>.</P> |
| <P><B>Throws:</B> nothing.</P> |
| </BLOCKQUOTE> |
| <h3><a name="dynamic_pointer_cast">dynamic_pointer_cast</a></h3> |
| <pre>template<class T, class U> |
| intrusive_ptr<T> dynamic_pointer_cast(intrusive_ptr<U> const & r);</pre> |
| <BLOCKQUOTE> |
| <P><B>Returns:</B> <code>intrusive_ptr<T>(dynamic_cast<T*>(r.get()))</code>.</P> |
| <P><B>Throws:</B> nothing.</P> |
| </BLOCKQUOTE> |
| <h3><a name="insertion-operator">operator<<</a></h3> |
| <pre>template<class E, class T, class Y> |
| std::basic_ostream<E, T> & operator<< (std::basic_ostream<E, T> & os, intrusive_ptr<Y> const & p);</pre> |
| <BLOCKQUOTE> |
| <p><STRONG>Effects:</STRONG> <code>os << p.get();</code>.</p> |
| <P><B>Returns:</B> <code>os</code>.</P> |
| </BLOCKQUOTE> |
| <hr> |
| <p> |
| $Date: 2008-07-12 07:37:16 -0400 (Sat, 12 Jul 2008) $</p> |
| <p> |
| <small>Copyright © 2003-2005 Peter Dimov. Distributed under the Boost Software License, Version |
| 1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or |
| copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p> |
| </body> |
| </html> |
