544 lines
19 KiB
XML
544 lines
19 KiB
XML
<section xmlns="http://docbook.org/ns/docbook" version="5.0"
|
|
xml:id="std.util.memory.shared_ptr" xreflabel="shared_ptr">
|
|
<?dbhtml filename="shared_ptr.html"?>
|
|
|
|
<info><title>shared_ptr</title>
|
|
<keywordset>
|
|
<keyword>
|
|
ISO C++
|
|
</keyword>
|
|
<keyword>
|
|
shared_ptr
|
|
</keyword>
|
|
</keywordset>
|
|
</info>
|
|
|
|
|
|
|
|
<para>
|
|
The shared_ptr class template stores a pointer, usually obtained via new,
|
|
and implements shared ownership semantics.
|
|
</para>
|
|
|
|
<section xml:id="shared_ptr.req"><info><title>Requirements</title></info>
|
|
|
|
|
|
<para>
|
|
</para>
|
|
|
|
<para>
|
|
The standard deliberately doesn't require a reference-counted
|
|
implementation, allowing other techniques such as a
|
|
circular-linked-list.
|
|
</para>
|
|
|
|
<para>
|
|
At the time of writing the C++0x working paper doesn't mention how
|
|
threads affect shared_ptr, but it is likely to follow the existing
|
|
practice set by <classname>boost::shared_ptr</classname>. The
|
|
shared_ptr in libstdc++ is derived from Boost's, so the same rules
|
|
apply.
|
|
</para>
|
|
|
|
<para>
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="shared_ptr.design_issues"><info><title>Design Issues</title></info>
|
|
|
|
|
|
|
|
<para>
|
|
The <classname>shared_ptr</classname> code is kindly donated to GCC by the Boost
|
|
project and the original authors of the code. The basic design and
|
|
algorithms are from Boost, the notes below describe details specific to
|
|
the GCC implementation. Names have been uglified in this implementation,
|
|
but the design should be recognisable to anyone familiar with the Boost
|
|
1.32 shared_ptr.
|
|
</para>
|
|
|
|
<para>
|
|
The basic design is an abstract base class, <code>_Sp_counted_base</code> that
|
|
does the reference-counting and calls virtual functions when the count
|
|
drops to zero.
|
|
Derived classes override those functions to destroy resources in a context
|
|
where the correct dynamic type is known. This is an application of the
|
|
technique known as type erasure.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section xml:id="shared_ptr.impl"><info><title>Implementation</title></info>
|
|
|
|
|
|
<section><info><title>Class Hierarchy</title></info>
|
|
|
|
|
|
<para>
|
|
A <classname>shared_ptr<T></classname> contains a pointer of
|
|
type <type>T*</type> and an object of type
|
|
<classname>__shared_count</classname>. The shared_count contains a
|
|
pointer of type <type>_Sp_counted_base*</type> which points to the
|
|
object that maintains the reference-counts and destroys the managed
|
|
resource.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><classname>_Sp_counted_base<Lp></classname></term>
|
|
<listitem>
|
|
<para>
|
|
The base of the hierarchy is parameterized on the lock policy (see below.)
|
|
_Sp_counted_base doesn't depend on the type of pointer being managed,
|
|
it only maintains the reference counts and calls virtual functions when
|
|
the counts drop to zero. The managed object is destroyed when the last
|
|
strong reference is dropped, but the _Sp_counted_base itself must exist
|
|
until the last weak reference is dropped.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><classname>_Sp_counted_base_impl<Ptr, Deleter, Lp></classname></term>
|
|
<listitem>
|
|
<para>
|
|
Inherits from _Sp_counted_base and stores a pointer of type <type>Ptr</type>
|
|
and a deleter of type <code>Deleter</code>. <code>_Sp_deleter</code> is
|
|
used when the user doesn't supply a custom deleter. Unlike Boost's, this
|
|
default deleter is not "checked" because GCC already issues a warning if
|
|
<function>delete</function> is used with an incomplete type.
|
|
This is the only derived type used by <classname>shared_ptr<Ptr></classname>
|
|
and it is never used by <classname>shared_ptr</classname>, which uses one of
|
|
the following types, depending on how the shared_ptr is constructed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><classname>_Sp_counted_ptr<Ptr, Lp></classname></term>
|
|
<listitem>
|
|
<para>
|
|
Inherits from _Sp_counted_base and stores a pointer of type <type>Ptr</type>,
|
|
which is passed to <function>delete</function> when the last reference is dropped.
|
|
This is the simplest form and is used when there is no custom deleter or
|
|
allocator.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><classname>_Sp_counted_deleter<Ptr, Deleter, Alloc></classname></term>
|
|
<listitem>
|
|
<para>
|
|
Inherits from _Sp_counted_ptr and adds support for custom deleter and
|
|
allocator. Empty Base Optimization is used for the allocator. This class
|
|
is used even when the user only provides a custom deleter, in which case
|
|
<classname>allocator</classname> is used as the allocator.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><classname>_Sp_counted_ptr_inplace<Tp, Alloc, Lp></classname></term>
|
|
<listitem>
|
|
<para>
|
|
Used by <code>allocate_shared</code> and <code>make_shared</code>.
|
|
Contains aligned storage to hold an object of type <type>Tp</type>,
|
|
which is constructed in-place with placement <function>new</function>.
|
|
Has a variadic template constructor allowing any number of arguments to
|
|
be forwarded to <type>Tp</type>'s constructor.
|
|
Unlike the other <classname>_Sp_counted_*</classname> classes, this one is parameterized on the
|
|
type of object, not the type of pointer; this is purely a convenience
|
|
that simplifies the implementation slightly.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section><info><title>Thread Safety</title></info>
|
|
|
|
|
|
<para>
|
|
C++0x-only features are: rvalue-ref/move support, allocator support,
|
|
aliasing constructor, make_shared & allocate_shared. Additionally,
|
|
the constructors taking <classname>auto_ptr</classname> parameters are
|
|
deprecated in C++0x mode.
|
|
</para>
|
|
|
|
<para>
|
|
The
|
|
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety">Thread
|
|
Safety</link> section of the Boost shared_ptr documentation says "shared_ptr
|
|
objects offer the same level of thread safety as built-in types."
|
|
The implementation must ensure that concurrent updates to separate shared_ptr
|
|
instances are correct even when those instances share a reference count e.g.
|
|
</para>
|
|
|
|
<programlisting>
|
|
shared_ptr<A> a(new A);
|
|
shared_ptr<A> b(a);
|
|
|
|
// Thread 1 // Thread 2
|
|
a.reset(); b.reset();
|
|
</programlisting>
|
|
|
|
<para>
|
|
The dynamically-allocated object must be destroyed by exactly one of the
|
|
threads. Weak references make things even more interesting.
|
|
The shared state used to implement shared_ptr must be transparent to the
|
|
user and invariants must be preserved at all times.
|
|
The key pieces of shared state are the strong and weak reference counts.
|
|
Updates to these need to be atomic and visible to all threads to ensure
|
|
correct cleanup of the managed resource (which is, after all, shared_ptr's
|
|
job!)
|
|
On multi-processor systems memory synchronisation may be needed so that
|
|
reference-count updates and the destruction of the managed resource are
|
|
race-free.
|
|
</para>
|
|
|
|
<para>
|
|
The function <function>_Sp_counted_base::_M_add_ref_lock()</function>, called when
|
|
obtaining a shared_ptr from a weak_ptr, has to test if the managed
|
|
resource still exists and either increment the reference count or throw
|
|
<classname>bad_weak_ptr</classname>.
|
|
In a multi-threaded program there is a potential race condition if the last
|
|
reference is dropped (and the managed resource destroyed) between testing
|
|
the reference count and incrementing it, which could result in a shared_ptr
|
|
pointing to invalid memory.
|
|
</para>
|
|
<para>
|
|
The Boost shared_ptr (as used in GCC) features a clever lock-free
|
|
algorithm to avoid the race condition, but this relies on the
|
|
processor supporting an atomic <emphasis>Compare-And-Swap</emphasis>
|
|
instruction. For other platforms there are fall-backs using mutex
|
|
locks. Boost (as of version 1.35) includes several different
|
|
implementations and the preprocessor selects one based on the
|
|
compiler, standard library, platform etc. For the version of
|
|
shared_ptr in libstdc++ the compiler and library are fixed, which
|
|
makes things much simpler: we have an atomic CAS or we don't, see Lock
|
|
Policy below for details.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section><info><title>Selecting Lock Policy</title></info>
|
|
|
|
|
|
<para>
|
|
</para>
|
|
|
|
<para>
|
|
There is a single <classname>_Sp_counted_base</classname> class,
|
|
which is a template parameterized on the enum
|
|
<type>__gnu_cxx::_Lock_policy</type>. The entire family of classes is
|
|
parameterized on the lock policy, right up to
|
|
<classname>__shared_ptr</classname>, <classname>__weak_ptr</classname> and
|
|
<classname>__enable_shared_from_this</classname>. The actual
|
|
<classname>std::shared_ptr</classname> class inherits from
|
|
<classname>__shared_ptr</classname> with the lock policy parameter
|
|
selected automatically based on the thread model and platform that
|
|
libstdc++ is configured for, so that the best available template
|
|
specialization will be used. This design is necessary because it would
|
|
not be conforming for <classname>shared_ptr</classname> to have an
|
|
extra template parameter, even if it had a default value. The
|
|
available policies are:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
<type>_S_Atomic</type>
|
|
</para>
|
|
<para>
|
|
Selected when GCC supports a builtin atomic compare-and-swap operation
|
|
on the target processor (see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html">Atomic
|
|
Builtins</link>.) The reference counts are maintained using a lock-free
|
|
algorithm and GCC's atomic builtins, which provide the required memory
|
|
synchronisation.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<type>_S_Mutex</type>
|
|
</para>
|
|
<para>
|
|
The _Sp_counted_base specialization for this policy contains a mutex,
|
|
which is locked in add_ref_lock(). This policy is used when GCC's atomic
|
|
builtins aren't available so explicit memory barriers are needed in places.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<type>_S_Single</type>
|
|
</para>
|
|
<para>
|
|
This policy uses a non-reentrant add_ref_lock() with no locking. It is
|
|
used when libstdc++ is built without <literal>--enable-threads</literal>.
|
|
</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
<para>
|
|
For all three policies, reference count increments and
|
|
decrements are done via the functions in
|
|
<filename>ext/atomicity.h</filename>, which detect if the program
|
|
is multi-threaded. If only one thread of execution exists in
|
|
the program then less expensive non-atomic operations are used.
|
|
</para>
|
|
</section>
|
|
|
|
<section><info><title>Dual C++0x and TR1 Implementation</title></info>
|
|
|
|
|
|
<para>
|
|
The interface of <classname>tr1::shared_ptr</classname> was extended for C++0x
|
|
with support for rvalue-references and the other features from N2351.
|
|
The <classname>_Sp_counted_base</classname> base class is implemented in
|
|
<filename>tr1/boost_sp_shared_count.h</filename> and is common to the TR1
|
|
and C++0x versions of <classname>shared_ptr</classname>.
|
|
</para>
|
|
|
|
<para>
|
|
The classes derived from <classname>_Sp_counted_base</classname> (see Class Hierarchy
|
|
above) and <classname>__shared_count</classname> are implemented separately for C++0x
|
|
and TR1, in <filename>bits/shared_ptr.h</filename> and
|
|
<filename>tr1/shared_ptr.h</filename> respectively.
|
|
</para>
|
|
|
|
<para>
|
|
The TR1 implementation is considered relatively stable, so is unlikely to
|
|
change unless bug fixes require it. If the code that is common to both
|
|
C++0x and TR1 modes needs to diverge further then it might be necessary to
|
|
duplicate <classname>_Sp_counted_base</classname> and only make changes to
|
|
the C++0x version.
|
|
</para>
|
|
</section>
|
|
|
|
<section><info><title>Related functions and classes</title></info>
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term><code>dynamic_pointer_cast</code>, <code>static_pointer_cast</code>,
|
|
<code>const_pointer_cast</code></term>
|
|
<listitem>
|
|
<para>
|
|
As noted in N2351, these functions can be implemented non-intrusively using
|
|
the alias constructor. However the aliasing constructor is only available
|
|
in C++0x mode, so in TR1 mode these casts rely on three non-standard
|
|
constructors in shared_ptr and __shared_ptr.
|
|
In C++0x mode these constructors and the related tag types are not needed.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><code>enable_shared_from_this</code></term>
|
|
<listitem>
|
|
<para>
|
|
The clever overload to detect a base class of type
|
|
<code>enable_shared_from_this</code> comes straight from Boost.
|
|
There is an extra overload for <code>__enable_shared_from_this</code> to
|
|
work smoothly with <code>__shared_ptr<Tp, Lp></code> using any lock
|
|
policy.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><code>make_shared</code>, <code>allocate_shared</code></term>
|
|
<listitem>
|
|
<para>
|
|
<code>make_shared</code> simply forwards to <code>allocate_shared</code>
|
|
with <code>std::allocator</code> as the allocator.
|
|
Although these functions can be implemented non-intrusively using the
|
|
alias constructor, if they have access to the implementation then it is
|
|
possible to save storage and reduce the number of heap allocations. The
|
|
newly constructed object and the _Sp_counted_* can be allocated in a single
|
|
block and the standard says implementations are "encouraged, but not required,"
|
|
to do so. This implementation provides additional non-standard constructors
|
|
(selected with the type <code>_Sp_make_shared_tag</code>) which create an
|
|
object of type <code>_Sp_counted_ptr_inplace</code> to hold the new object.
|
|
The returned <code>shared_ptr<A></code> needs to know the address of the
|
|
new <code>A</code> object embedded in the <code>_Sp_counted_ptr_inplace</code>,
|
|
but it has no way to access it.
|
|
This implementation uses a "covert channel" to return the address of the
|
|
embedded object when <code>get_deleter<_Sp_make_shared_tag>()</code>
|
|
is called. Users should not try to use this.
|
|
As well as the extra constructors, this implementation also needs some
|
|
members of _Sp_counted_deleter to be protected where they could otherwise
|
|
be private.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<!--- XXX
|
|
<listitem>
|
|
<type>_Sp_counted_base<Lp></type>
|
|
<para>
|
|
The base of the hierarchy is parameterized on the lock policy alone.
|
|
_Sp_counted_base doesn't depend on the type of pointer being managed,
|
|
it only maintains the reference counts and calls virtual functions when
|
|
the counts drop to zero. The managed object is destroyed when the last
|
|
strong reference is dropped, but the _Sp_counted_base itself must exist
|
|
until the last weak reference is dropped.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<type>_Sp_counted_base_impl<Ptr, Deleter, Lp></type>
|
|
<para>
|
|
Inherits from _Sp_counted_base and stores a pointer of type <code>Ptr</code>
|
|
and a deleter of type <code>Deleter</code>. <code>_Sp_deleter</code> is
|
|
used when the user doesn't supply a custom deleter. Unlike Boost's, this
|
|
default deleter is not "checked" because GCC already issues a warning if
|
|
<code>delete</code> is used with an incomplete type.
|
|
This is the only derived type used by <code>tr1::shared_ptr<Ptr></code>
|
|
and it is never used by <code>std::shared_ptr</code>, which uses one of
|
|
the following types, depending on how the shared_ptr is constructed.
|
|
</para>
|
|
</listitem>
|
|
-->
|
|
|
|
<section xml:id="shared_ptr.using"><info><title>Use</title></info>
|
|
|
|
|
|
<section><info><title>Examples</title></info>
|
|
|
|
<para>
|
|
Examples of use can be found in the testsuite, under
|
|
<filename class="directory">testsuite/tr1/2_general_utilities/shared_ptr</filename>,
|
|
<filename class="directory">testsuite/20_util/shared_ptr</filename>
|
|
and
|
|
<filename class="directory">testsuite/20_util/weak_ptr</filename>.
|
|
</para>
|
|
</section>
|
|
|
|
<section><info><title>Unresolved Issues</title></info>
|
|
|
|
<para>
|
|
The <emphasis><classname>shared_ptr</classname> atomic access</emphasis>
|
|
clause in the C++0x working draft is not implemented in GCC.
|
|
</para>
|
|
|
|
<para>
|
|
The <type>_S_single</type> policy uses atomics when used in MT
|
|
code, because it uses the same dispatcher functions that check
|
|
<function>__gthread_active_p()</function>. This could be
|
|
addressed by providing template specialisations for some members
|
|
of <classname>_Sp_counted_base<_S_single></classname>.
|
|
</para>
|
|
|
|
<para>
|
|
Unlike Boost, this implementation does not use separate classes
|
|
for the pointer+deleter and pointer+deleter+allocator cases in
|
|
C++0x mode, combining both into _Sp_counted_deleter and using
|
|
<classname>allocator</classname> when the user doesn't specify
|
|
an allocator. If it was found to be beneficial an additional
|
|
class could easily be added. With the current implementation,
|
|
the _Sp_counted_deleter and __shared_count constructors taking a
|
|
custom deleter but no allocator are technically redundant and
|
|
could be removed, changing callers to always specify an
|
|
allocator. If a separate pointer+deleter class was added the
|
|
__shared_count constructor would be needed, so it has been kept
|
|
for now.
|
|
</para>
|
|
|
|
<para>
|
|
The hack used to get the address of the managed object from
|
|
<function>_Sp_counted_ptr_inplace::_M_get_deleter()</function>
|
|
is accessible to users. This could be prevented if
|
|
<function>get_deleter<_Sp_make_shared_tag>()</function>
|
|
always returned NULL, since the hack only needs to work at a
|
|
lower level, not in the public API. This wouldn't be difficult,
|
|
but hasn't been done since there is no danger of accidental
|
|
misuse: users already know they are relying on unsupported
|
|
features if they refer to implementation details such as
|
|
_Sp_make_shared_tag.
|
|
</para>
|
|
|
|
<para>
|
|
tr1::_Sp_deleter could be a private member of tr1::__shared_count but it
|
|
would alter the ABI.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section xml:id="shared_ptr.ack"><info><title>Acknowledgments</title></info>
|
|
|
|
|
|
<para>
|
|
The original authors of the Boost shared_ptr, which is really nice
|
|
code to work with, Peter Dimov in particular for his help and
|
|
invaluable advice on thread safety. Phillip Jordan and Paolo
|
|
Carlini for the lock policy implementation.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<bibliography xml:id="shared_ptr.biblio"><info><title>Bibliography</title></info>
|
|
|
|
|
|
<biblioentry>
|
|
<biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm" class="uri">
|
|
</biblioid>
|
|
<citetitle>
|
|
Improving shared_ptr for C++0x, Revision 2
|
|
</citetitle>
|
|
<subtitle>
|
|
N2351
|
|
</subtitle>
|
|
</biblioentry>
|
|
|
|
<biblioentry>
|
|
<biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html" class="uri">
|
|
</biblioid>
|
|
<citetitle>
|
|
C++ Standard Library Active Issues List
|
|
</citetitle>
|
|
<subtitle>
|
|
N2456
|
|
</subtitle>
|
|
</biblioentry>
|
|
|
|
<biblioentry>
|
|
<biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf" class="uri">
|
|
</biblioid>
|
|
<citetitle>
|
|
Working Draft, Standard for Programming Language C++
|
|
</citetitle>
|
|
<subtitle>
|
|
N2461
|
|
</subtitle>
|
|
</biblioentry>
|
|
|
|
<biblioentry>
|
|
<biblioid xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://boost.org/libs/smart_ptr/shared_ptr.htm" class="uri">shared_ptr
|
|
</biblioid>
|
|
<citetitle>
|
|
Boost C++ Libraries documentation, shared_ptr
|
|
</citetitle>
|
|
<subtitle>
|
|
N2461
|
|
</subtitle>
|
|
</biblioentry>
|
|
|
|
</bibliography>
|
|
|
|
</section>
|