This provides a way to escape from automatic reference counting, and taking manual control of the reference. Useful when interfacing to a C API that expects a pointer with an elevated reference count. Similar to std::unique_ptr<>::release(). --- include/boost/smart_ptr/intrusive_ptr.hpp | 7 +++++++ intrusive_ptr.html | 23 ++++++++++++++++++----- test/intrusive_ptr_test.cpp | 7 +++++++ 3 files changed, 32 insertions(+), 5 deletions(-) diff --git a/include/boost/smart_ptr/intrusive_ptr.hpp b/include/boost/smart_ptr/intrusive_ptr.hpp index a855a10..8c73fe2 100644 --- a/include/boost/smart_ptr/intrusive_ptr.hpp +++ b/include/boost/smart_ptr/intrusive_ptr.hpp @@ -151,6 +151,13 @@ public: return px; } + T * release() BOOST_NOEXCEPT + { + T * ret = px; + px = 0; + return ret; + } + T & operator*() const { BOOST_ASSERT( px != 0 ); diff --git a/intrusive_ptr.html b/intrusive_ptr.html index 562d27a..ef6238b 100644 --- a/intrusive_ptr.html +++ b/intrusive_ptr.html @@ -71,6 +71,7 @@ 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 + T * <A href="#release" >release</A>(); // never throws operator <A href="#conversions" ><i>unspecified-bool-type</i></A>() const; // never throws @@ -174,11 +175,23 @@ intrusive_ptr & operator=(T * r);</pre> <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> + <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="release">release</a></h3> + <pre>T * release(); // never throws</pre> + <blockquote> + <p><b>Returns:</b> the stored pointer.</p> + <p><b>Throws:</b> nothing.</p> + <p><b>Postconditions:</b> <code>get() == 0</code>.</p> + <p><b>Notes:</b> The returned pointer has an elevated reference count. This + allows conversion of an <b>intrusive_ptr</b> back to a raw pointer, + without the performance overhead of acquiring and dropping an extra + reference. It can be viewed as the complement of the + non-reference-incrementing constructor.</p> + </blockquote> <h3><a name="conversions">conversions</a></h3> <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre> <blockquote> diff --git a/test/intrusive_ptr_test.cpp b/test/intrusive_ptr_test.cpp index 614a9cb..90248fe 100644 --- a/test/intrusive_ptr_test.cpp +++ b/test/intrusive_ptr_test.cpp @@ -330,6 +330,13 @@ void test() BOOST_TEST(get_pointer(px) == px.get()); } + + { + boost::intrusive_ptr<X> px(new X); + X* released = px.release(); + BOOST_TEST(released->use_count() == 1); + delete released; + } } } // namespace n_access -- 1.8.3.1