mirror of
https://github.com/boostorg/smart_ptr.git
synced 2025-07-30 12:47:28 +02:00
Update documentation.
This commit is contained in:
Peter Dimov
@ -2,16 +2,16 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>pointer_cast</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 text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
||||
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
||||
width="277" align="middle" border="0">pointer_cast</h1>
|
||||
width="277" align="middle" border="0" />pointer_cast</h1>
|
||||
<p>The pointer cast functions (<code>boost::static_pointer_cast</code> <code>boost::dynamic_pointer_cast</code>
|
||||
<code>boost::reinterpret_pointer_cast</code> <code>boost::const_pointer_cast</code>)
|
||||
provide a way to write generic pointer castings for raw pointers, std::shared_ptr and std::unique_ptr. The functions
|
||||
are defined in <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A>.</CITE></p>
|
||||
<P>There is test/example code in <CITE><A href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</A></CITE>.</p>
|
||||
provide a way to write generic pointer castings for raw pointers, <code>std::shared_ptr</code> and <code>std::unique_ptr</code>. The functions
|
||||
are defined in <cite><a href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</a>.</cite></p>
|
||||
<p>There is test/example code in <cite><a href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</a></cite>.</p>
|
||||
<h2><a name="rationale">Rationale</a></h2>
|
||||
<P>Boost smart pointers usually overload those functions to provide a mechanism to
|
||||
emulate pointers casts. For example, <code>boost::shared_ptr<...></code> implements
|
||||
@ -20,15 +20,15 @@
|
||||
template<class T, class U>
|
||||
shared_ptr<T> static_pointer_cast(shared_ptr<U> const &r);
|
||||
</pre>
|
||||
<P>Pointer cast functions from <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A></CITE>
|
||||
<p>Pointer cast functions from <cite><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A></CITE>
|
||||
are overloads of <code>boost::static_pointer_cast</code>, <code>boost::dynamic_pointer_cast</code>,
|
||||
<code>boost::reinterpret_pointer_cast</code> and <code>boost::const_pointer_cast</code>
|
||||
for raw pointers, std::shared_ptr and std::unique_ptr. This way when developing pointer type independent classes,
|
||||
for example, memory managers or shared memory compatible classes, the same code
|
||||
can be used for raw and smart pointers.</p>
|
||||
<H2><A name="synopsis">Synopsis</A></H2>
|
||||
<BLOCKQUOTE>
|
||||
<PRE>
|
||||
for raw pointers, <code>std::shared_ptr</code> and <code>std::unique_ptr</code>. This way when developing
|
||||
pointer type independent classes, for example, memory managers or shared memory compatible classes, the same
|
||||
code can be used for raw and smart pointers.</p>
|
||||
<h2><a name="synopsis">Synopsis</a></h2>
|
||||
<blockquote>
|
||||
<pre>
|
||||
namespace boost {
|
||||
|
||||
template<class T, class U>
|
||||
@ -48,84 +48,91 @@ inline T* reinterpret_pointer_cast(U *ptr)
|
||||
{ return reinterpret_cast<T*>(ptr); }
|
||||
|
||||
template<class T, class U>
|
||||
inline std::shared_ptr<U> static_pointer_cast(std::shared_ptr<T> ptr);
|
||||
inline std::shared_ptr<T> static_pointer_cast(std::shared_ptr<U> const& r);
|
||||
|
||||
template<class T, class U>
|
||||
inline std::shared_ptr<U> dynamic_pointer_cast(std::shared_ptr<T> ptr);
|
||||
inline std::shared_ptr<T> dynamic_pointer_cast(std::shared_ptr<U> const& r);
|
||||
|
||||
template<class T, class U>
|
||||
inline std::shared_ptr<U> const_pointer_cast(std::shared_ptr<T> ptr);
|
||||
inline std::shared_ptr<T> const_pointer_cast(std::shared_ptr<U> const& r);
|
||||
|
||||
template<class T, class U>
|
||||
inline std::shared_ptr<U> reinterpret_pointer_cast(std::shared_ptr<T> ptr);
|
||||
inline std::shared_ptr<T> reinterpret_pointer_cast(std::shared_ptr<U> const& r);
|
||||
|
||||
template<class T, class U>
|
||||
inline std::unique_ptr<U> static_pointer_cast(std::unique_ptr<T> &&ptr);
|
||||
inline std::unique_ptr<T> static_pointer_cast(std::unique_ptr<U>&& r);
|
||||
|
||||
template<class T, class U>
|
||||
inline std::unique_ptr<U> dynamic_pointer_cast(std::unique_ptr<T> &&ptr);
|
||||
inline std::unique_ptr<T> dynamic_pointer_cast(std::unique_ptr<U>&& r);
|
||||
|
||||
template<class T, class U>
|
||||
inline std::unique_ptr<U> const_pointer_cast(std::unique_ptr<T> &&ptr);
|
||||
inline std::unique_ptr<T> const_pointer_cast(std::unique_ptr<U>&& r);
|
||||
|
||||
template<class T, class U>
|
||||
inline std::unique_ptr<U> reinterpret_pointer_cast(std::unique_ptr<T> &&ptr);
|
||||
inline std::unique_ptr<T> reinterpret_pointer_cast(std::unique_ptr<U>&& r);
|
||||
|
||||
} // namespace boost
|
||||
</PRE>
|
||||
</BLOCKQUOTE>
|
||||
<P>As you can see from the above synopsis, the pointer cast functions for raw pointers are just
|
||||
wrappers around standard C++ cast operators.</P>
|
||||
</pre>
|
||||
</blockquote>
|
||||
<p>As you can see from the above synopsis, the pointer cast functions for raw pointers are just
|
||||
wrappers around standard C++ cast operators.</p>
|
||||
|
||||
<H2><A name="memory_safety">Memory Safety</A></H2>
|
||||
<P>It is possible to write unsafe code, when upcasting to a base type without virtual destructor.
|
||||
Consider the following example:</P>
|
||||
<PRE>
|
||||
#include <memory>
|
||||
#include <utility>
|
||||
#include <boost/pointer_cast.hpp>
|
||||
#include <boost/make_unique.hpp>
|
||||
<p>The pointer casts for <code>std::shared_ptr</code> are aliases of the corresponding standard
|
||||
functions with the same names and equivalent to <a href="shared_ptr.htm#static_pointer_cast">the
|
||||
functions taking <code>boost::shared_ptr</code></a>.</p>
|
||||
|
||||
int destructed = 0;
|
||||
<p>The pointer casts for <code>std::unique_ptr</code> are documented below.</p>
|
||||
|
||||
struct base {
|
||||
~base() {
|
||||
// ...
|
||||
}
|
||||
};
|
||||
<h3 id="static_pointer_cast">static_pointer_cast</h3>
|
||||
<pre>template<class T, class U>
|
||||
unique_ptr<T> static_pointer_cast(unique_ptr<U>&& r); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Requires:</b> The expression <code>static_cast<T*>( (U*)0 )</code>
|
||||
must be well-formed.</p>
|
||||
<p><b>Returns:</b> <code>unique_ptr<T>( static_cast<typename unique_ptr<T>::element_type*>(r.release()) )</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
<p><b>Notes:</b> the seemingly equivalent expression
|
||||
<code>unique_ptr<T>(static_cast<T*>(r.get()))</code>
|
||||
will eventually result in undefined behavior, attempting to delete the same
|
||||
object twice.</p>
|
||||
</blockquote>
|
||||
<h3 id="const_pointer_cast">const_pointer_cast</h3>
|
||||
<pre>template<class T, class U>
|
||||
unique_ptr<T> const_pointer_cast(unique_ptr<U>&& r); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Requires:</b> The expression <code>const_cast<T*>( (U*)0 )</code>
|
||||
must be well-formed.</p>
|
||||
<p><b>Returns:</b> <code>unique_ptr<T>( const_cast<typename unique_ptr<T>::element_type*>(r.release()) )</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3 id="dynamic_pointer_cast">dynamic_pointer_cast</h3>
|
||||
<pre>template<class T, class U>
|
||||
unique_ptr<T> dynamic_pointer_cast(unique_ptr<U>&& r);</pre>
|
||||
<blockquote>
|
||||
<p><b>Requires:</b> The expression <code>dynamic_cast<T*>( (U*)0 )</code>
|
||||
must be well-formed. <code>T</code> must have a virtual destructor.</p>
|
||||
<p><b>Returns:</b></p>
|
||||
<ul>
|
||||
<li>
|
||||
When <code>dynamic_cast<typename unique_ptr<T>::element_type*>(r.get())</code> returns a nonzero value,
|
||||
<code>unique_ptr<T>(dynamic_cast<typename unique_ptr<T>::element_type*>(r.release()))</code>;</li>
|
||||
<li>
|
||||
Otherwise, <code>unique_ptr<T>()</code>.</li></ul>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
<h3 id="reinterpret_pointer_cast">reinterpret_pointer_cast</h3>
|
||||
<pre>template<class T, class U>
|
||||
unique_ptr<T> reinterpret_pointer_cast(unique_ptr<U>&& r); // never throws</pre>
|
||||
<blockquote>
|
||||
<p><b>Requires:</b> The expression <code>reinterpret_cast<T*>( (U*)0 )</code>
|
||||
must be well-formed.</p>
|
||||
<p><b>Returns:</b> <code>unique_ptr<T>( reinterpret_cast<typename unique_ptr<T>::element_type*>(r.release()) )</code>.</p>
|
||||
<p><b>Throws:</b> nothing.</p>
|
||||
</blockquote>
|
||||
|
||||
struct child : base {
|
||||
virtual ~child() {
|
||||
destructed++;
|
||||
}
|
||||
}
|
||||
|
||||
int main() {
|
||||
{
|
||||
std::unique_ptr<child> tmp = boost::make_unique<child>();
|
||||
std::unique_ptr<base> sink = boost::static_pointer_cast<base>( std::move(tmp) );
|
||||
}
|
||||
|
||||
// child::~child was never called
|
||||
assert(destructed == 0);
|
||||
|
||||
return 0;
|
||||
}
|
||||
</PRE>
|
||||
<P>In this example, the child destructor child::~child was never called, because the child* in tmp
|
||||
was downcast to a base* and moved into sink. The destructor of tmp did essentially nothing, because
|
||||
it contained nullptr during destruction; sink deleted the pointer, but since base::~base is non-virtual
|
||||
the child destructor was never called.</P>
|
||||
<P>boost::static_pointer_cast and boost::dynamic_pointer_cast for std::unique_ptr prevent the above scenario
|
||||
by raising a compiler error when such a cast is detected.</P>
|
||||
<P>The overloads for std::shared_ptr and boost::shared_ptr are not prone to this problem, since they internally
|
||||
always store the original pointer with the original type.</P>
|
||||
<P>The plain pointer casts are in principle also prone to that problem, but it is assumed that raw pointers
|
||||
are non-owning, so no checking is performed.</P>
|
||||
|
||||
<H2><A name="example">Example</A></H2>
|
||||
<BLOCKQUOTE>
|
||||
<PRE>
|
||||
<h2><a name="example">Example</a></h2>
|
||||
<blockquote>
|
||||
<pre>
|
||||
#include <boost/pointer_cast.hpp>
|
||||
#include <boost/shared_ptr.hpp>
|
||||
|
||||
@ -150,28 +157,27 @@ void check_if_it_is_derived(const BasePtr &ptr)
|
||||
|
||||
int main()
|
||||
{
|
||||
<I>// Create a raw and a shared_ptr</I>
|
||||
<em>// Create a raw and a shared_ptr</em>
|
||||
|
||||
base *ptr = new derived;
|
||||
boost::shared_ptr<base> sptr(new derived);
|
||||
|
||||
<I>// Check that base pointer points actually to derived class</I>
|
||||
<em>// Check that base pointer points actually to derived class</em>
|
||||
|
||||
check_if_it_is_derived(ptr);
|
||||
check_if_it_is_derived(sptr);
|
||||
|
||||
// <EM>Ok!</EM>
|
||||
<em>// Ok!</em>
|
||||
|
||||
delete ptr;
|
||||
return 0;
|
||||
}</PRE>
|
||||
</BLOCKQUOTE>
|
||||
<P>The example demonstrates how the generic pointer casts help us create pointer
|
||||
independent code.</P>
|
||||
<hr>
|
||||
<p>$Date$</p>
|
||||
}</pre>
|
||||
</blockquote>
|
||||
<p>The example demonstrates how the generic pointer casts help us create pointer
|
||||
independent code.</p>
|
||||
<hr />
|
||||
<p>Copyright 2005 Ion Gazta<74>aga. Use, modification, and distribution are subject to
|
||||
the Boost Software License, Version 1.0. (See accompanying file <A href="../../LICENSE_1_0.txt">
|
||||
LICENSE_1_0.txt</A> or a copy at <<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>>.)</p>
|
||||
the Boost Software License, Version 1.0. (See accompanying file <a href="../../LICENSE_1_0.txt">
|
||||
LICENSE_1_0.txt</a> or a copy at <<a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>>.)</p>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
Reference in New Issue
Block a user