OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [libstdc++-v3/] [doc/] [html/] [manual/] [shared_ptr.html] - Blame information for rev 424

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 424 jeremybenn 
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>shared_ptr</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      shared_ptr&#10;    " /><meta name="keywords" content="&#10;      ISO C++&#10;    , &#10;      library&#10;    " /><link rel="home" href="../spine.html" title="The GNU C++ Library Documentation" /><link rel="up" href="memory.html" title="Chapter 11. Memory" /><link rel="prev" href="auto_ptr.html" title="auto_ptr" /><link rel="next" href="traits.html" title="Chapter 12. Traits" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">shared_ptr</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="auto_ptr.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Memory</th><td width="20%" align="right"> <a accesskey="n" href="traits.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="shared_ptr"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.util.memory.shared_ptr"></a>shared_ptr</h2></div></div></div><p>
4 
The shared_ptr class template stores a pointer, usually obtained via new,
5 
and implements shared ownership semantics.
6 
</p><div class="sect2" title="Requirements"><div class="titlepage"><div><div><h3 class="title"><a id="shared_ptr.req"></a>Requirements</h3></div></div></div><p>
7 
  </p><p>
8 
    The standard deliberately doesn't require a reference-counted
9 
    implementation, allowing other techniques such as a
10 
    circular-linked-list.
11 
  </p><p>
12 
    At the time of writing the C++0x working paper doesn't mention how
13 
    threads affect shared_ptr, but it is likely to follow the existing
14 
    practice set by <code class="classname">boost::shared_ptr</code>.  The
15 
    shared_ptr in libstdc++ is derived from Boost's, so the same rules
16 
    apply.
17 
  </p><p>
18 
  </p></div><div class="sect2" title="Design Issues"><div class="titlepage"><div><div><h3 class="title"><a id="shared_ptr.design_issues"></a>Design Issues</h3></div></div></div><p>
19 
The <code class="classname">shared_ptr</code> code is kindly donated to GCC by the Boost
20 
project and the original authors of the code. The basic design and
21 
algorithms are from Boost, the notes below describe details specific to
22 
the GCC implementation. Names have been uglified in this implementation,
23 
but the design should be recognisable to anyone familiar with the Boost
24 
1.32 shared_ptr.
25 
  </p><p>
26 
The basic design is an abstract base class, <code class="code">_Sp_counted_base</code> that
27 
does the reference-counting and calls virtual functions when the count
28 
drops to zero.
29 
Derived classes override those functions to destroy resources in a context
30 
where the correct dynamic type is known. This is an application of the
31 
technique known as type erasure.
32 
  </p></div><div class="sect2" title="Implementation"><div class="titlepage"><div><div><h3 class="title"><a id="shared_ptr.impl"></a>Implementation</h3></div></div></div><div class="sect3" title="Class Hierarchy"><div class="titlepage"><div><div><h4 class="title"><a id="id628890"></a>Class Hierarchy</h4></div></div></div><p>
33 
A <code class="classname">shared_ptr&lt;T&gt;</code> contains a pointer of
34 
type <span class="type">T*</span> and an object of type
35 
<code class="classname">__shared_count</code>. The shared_count contains a
36 
pointer of type <span class="type">_Sp_counted_base*</span> which points to the
37 
object that maintains the reference-counts and destroys the managed
38 
resource.
39 
    </p><div class="variablelist"><dl><dt><span class="term"><code class="classname">_Sp_counted_base&lt;Lp&gt;</code></span></dt><dd><p>
40 
The base of the hierarchy is parameterized on the lock policy alone.
41 
_Sp_counted_base doesn't depend on the type of pointer being managed,
42 
it only maintains the reference counts and calls virtual functions when
43 
the counts drop to zero. The managed object is destroyed when the last
44 
strong reference is dropped, but the _Sp_counted_base itself must exist
45 
until the last weak reference is dropped.
46 
    </p></dd><dt><span class="term"><code class="classname">_Sp_counted_base_impl&lt;Ptr, Deleter, Lp&gt;</code></span></dt><dd><p>
47 
Inherits from _Sp_counted_base and stores a pointer of type <span class="type">Ptr</span>
48 
and a deleter of type <code class="code">Deleter</code>.  <code class="code">_Sp_deleter</code> is
49 
used when the user doesn't supply a custom deleter. Unlike Boost's, this
50 
default deleter is not "checked" because GCC already issues a warning if
51 
<code class="function">delete</code> is used with an incomplete type.
52 
This is the only derived type used by <code class="classname">shared_ptr&lt;Ptr&gt;</code>
53 
and it is never used by <code class="classname">shared_ptr</code>, which uses one of
54 
the following types, depending on how the shared_ptr is constructed.
55 
    </p></dd><dt><span class="term"><code class="classname">_Sp_counted_ptr&lt;Ptr, Lp&gt;</code></span></dt><dd><p>
56 
Inherits from _Sp_counted_base and stores a pointer of type <span class="type">Ptr</span>,
57 
which is passed to <code class="function">delete</code> when the last reference is dropped.
58 
This is the simplest form and is used when there is no custom deleter or
59 
allocator.
60 
    </p></dd><dt><span class="term"><code class="classname">_Sp_counted_deleter&lt;Ptr, Deleter, Alloc&gt;</code></span></dt><dd><p>
61 
Inherits from _Sp_counted_ptr and adds support for custom deleter and
62 
allocator. Empty Base Optimization is used for the allocator. This class
63 
is used even when the user only provides a custom deleter, in which case
64 
<code class="classname">allocator</code> is used as the allocator.
65 
    </p></dd><dt><span class="term"><code class="classname">_Sp_counted_ptr_inplace&lt;Tp, Alloc, Lp&gt;</code></span></dt><dd><p>
66 
Used by <code class="code">allocate_shared</code> and <code class="code">make_shared</code>.
67 
Contains aligned storage to hold an object of type <span class="type">Tp</span>,
68 
which is constructed in-place with placement <code class="function">new</code>.
69 
Has a variadic template constructor allowing any number of arguments to
70 
be forwarded to <span class="type">Tp</span>'s constructor.
71 
Unlike the other <code class="classname">_Sp_counted_*</code> classes, this one is parameterized on the
72 
type of object, not the type of pointer; this is purely a convenience
73 
that simplifies the implementation slightly.
74 
    </p></dd></dl></div></div><div class="sect3" title="Thread Safety"><div class="titlepage"><div><div><h4 class="title"><a id="id612958"></a>Thread Safety</h4></div></div></div><p>
75 
The interface of <code class="classname">tr1::shared_ptr</code> was extended for C++0x
76 
with support for rvalue-references and the other features from
77 
N2351. As with other libstdc++ headers shared by TR1 and C++0x,
78 
boost_shared_ptr.h uses conditional compilation, based on the macros
79 
<code class="constant">_GLIBCXX_INCLUDE_AS_CXX0X</code> and
80 
<code class="constant">_GLIBCXX_INCLUDE_AS_TR1</code>, to enable and disable
81 
features.
82 
    </p><p>
83 
C++0x-only features are: rvalue-ref/move support, allocator support,
84 
aliasing constructor, make_shared &amp; allocate_shared. Additionally,
85 
the constructors taking <code class="classname">auto_ptr</code> parameters are
86 
deprecated in C++0x mode.
87 
    </p><p>
88 
The
89 
<a class="ulink" href="http://boost.org/libs/smart_ptr/shared_ptr.htm#ThreadSafety" target="_top">Thread
90 
Safety</a> section of the Boost shared_ptr documentation says "shared_ptr
91 
objects offer the same level of thread safety as built-in types."
92 
The implementation must ensure that concurrent updates to separate shared_ptr
93 
instances are correct even when those instances share a reference count e.g.
94 
</p><pre class="programlisting">
95 
shared_ptr&lt;A&gt; a(new A);
96 
shared_ptr&lt;A&gt; b(a);
97 
 
98 
// Thread 1     // Thread 2
99 
   a.reset();      b.reset();
100 
</pre><p>
101 
The dynamically-allocated object must be destroyed by exactly one of the
102 
threads. Weak references make things even more interesting.
103 
The shared state used to implement shared_ptr must be transparent to the
104 
user and invariants must be preserved at all times.
105 
The key pieces of shared state are the strong and weak reference counts.
106 
Updates to these need to be atomic and visible to all threads to ensure
107 
correct cleanup of the managed resource (which is, after all, shared_ptr's
108 
job!)
109 
On multi-processor systems memory synchronisation may be needed so that
110 
reference-count updates and the destruction of the managed resource are
111 
race-free.
112 
</p><p>
113 
The function <code class="function">_Sp_counted_base::_M_add_ref_lock()</code>, called when
114 
obtaining a shared_ptr from a weak_ptr, has to test if the managed
115 
resource still exists and either increment the reference count or throw
116 
<code class="classname">bad_weak_ptr</code>.
117 
In a multi-threaded program there is a potential race condition if the last
118 
reference is dropped (and the managed resource destroyed) between testing
119 
the reference count and incrementing it, which could result in a shared_ptr
120 
pointing to invalid memory.
121 
</p><p>
122 
The Boost shared_ptr (as used in GCC) features a clever lock-free
123 
algorithm to avoid the race condition, but this relies on the
124 
processor supporting an atomic <span class="emphasis"><em>Compare-And-Swap</em></span>
125 
instruction. For other platforms there are fall-backs using mutex
126 
locks.  Boost (as of version 1.35) includes several different
127 
implementations and the preprocessor selects one based on the
128 
compiler, standard library, platform etc. For the version of
129 
shared_ptr in libstdc++ the compiler and library are fixed, which
130 
makes things much simpler: we have an atomic CAS or we don't, see Lock
131 
Policy below for details.
132 
</p></div><div class="sect3" title="Selecting Lock Policy"><div class="titlepage"><div><div><h4 class="title"><a id="id637767"></a>Selecting Lock Policy</h4></div></div></div><p>
133 
    </p><p>
134 
There is a single <code class="classname">_Sp_counted_base</code> class,
135 
which is a template parameterized on the enum
136 
<span class="type">__gnu_cxx::_Lock_policy</span>.  The entire family of classes is
137 
parameterized on the lock policy, right up to
138 
<code class="classname">__shared_ptr</code>, <code class="classname">__weak_ptr</code> and
139 
<code class="classname">__enable_shared_from_this</code>. The actual
140 
<code class="classname">std::shared_ptr</code> class inherits from
141 
<code class="classname">__shared_ptr</code> with the lock policy parameter
142 
selected automatically based on the thread model and platform that
143 
libstdc++ is configured for, so that the best available template
144 
specialization will be used. This design is necessary because it would
145 
not be conforming for <code class="classname">shared_ptr</code> to have an
146 
extra template parameter, even if it had a default value.  The
147 
available policies are:
148 
    </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
149 
       <span class="type">_S_Atomic</span>
150 
       </p><p>
151 
Selected when GCC supports a builtin atomic compare-and-swap operation
152 
on the target processor (see <a class="ulink" href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html" target="_top">Atomic
153 
Builtins</a>.)  The reference counts are maintained using a lock-free
154 
algorithm and GCC's atomic builtins, which provide the required memory
155 
synchronisation.
156 
       </p></li><li class="listitem"><p>
157 
       <span class="type">_S_Mutex</span>
158 
       </p><p>
159 
The _Sp_counted_base specialization for this policy contains a mutex,
160 
which is locked in add_ref_lock(). This policy is used when GCC's atomic
161 
builtins aren't available so explicit memory barriers are needed in places.
162 
       </p></li><li class="listitem"><p>
163 
       <span class="type">_S_Single</span>
164 
       </p><p>
165 
This policy uses a non-reentrant add_ref_lock() with no locking. It is
166 
used when libstdc++ is built without <code class="literal">--enable-threads</code>.
167 
       </p></li></ol></div><p>
168 
       For all three policies, reference count increments and
169 
       decrements are done via the functions in
170 
       <code class="filename">ext/atomicity.h</code>, which detect if the program
171 
       is multi-threaded.  If only one thread of execution exists in
172 
       the program then less expensive non-atomic operations are used.
173 
     </p></div><div class="sect3" title="Dual C++0x and TR1 Implementation"><div class="titlepage"><div><div><h4 class="title"><a id="id618991"></a>Dual C++0x and TR1 Implementation</h4></div></div></div><p>
174 
The classes derived from <code class="classname">_Sp_counted_base</code> (see Class Hierarchy
175 
below) and <code class="classname">__shared_count</code> are implemented separately for C++0x
176 
and TR1, in <code class="filename">bits/boost_sp_shared_count.h</code> and
177 
<code class="filename">tr1/boost_sp_shared_count.h</code> respectively.  All other classes
178 
including <code class="classname">_Sp_counted_base</code> are shared by both implementations.
179 
</p><p>
180 
The TR1 implementation is considered relatively stable, so is unlikely to
181 
change unless bug fixes require it.  If the code that is common to both
182 
C++0x and TR1 modes needs to diverge further then it might be necessary to
183 
duplicate additional classes and only make changes to the C++0x versions.
184 
</p></div><div class="sect3" title="Related functions and classes"><div class="titlepage"><div><div><h4 class="title"><a id="id589355"></a>Related functions and classes</h4></div></div></div><div class="variablelist"><dl><dt><span class="term"><code class="code">dynamic_pointer_cast</code>, <code class="code">static_pointer_cast</code>,
185 
<code class="code">const_pointer_cast</code></span></dt><dd><p>
186 
As noted in N2351, these functions can be implemented non-intrusively using
187 
the alias constructor.  However the aliasing constructor is only available
188 
in C++0x mode, so in TR1 mode these casts rely on three non-standard
189 
constructors in shared_ptr and __shared_ptr.
190 
In C++0x mode these constructors and the related tag types are not needed.
191 
    </p></dd><dt><span class="term"><code class="code">enable_shared_from_this</code></span></dt><dd><p>
192 
The clever overload to detect a base class of type
193 
<code class="code">enable_shared_from_this</code> comes straight from Boost.
194 
There is an extra overload for <code class="code">__enable_shared_from_this</code> to
195 
work smoothly with <code class="code">__shared_ptr&lt;Tp, Lp&gt;</code> using any lock
196 
policy.
197 
    </p></dd><dt><span class="term"><code class="code">make_shared</code>, <code class="code">allocate_shared</code></span></dt><dd><p>
198 
<code class="code">make_shared</code> simply forwards to <code class="code">allocate_shared</code>
199 
with <code class="code">std::allocator</code> as the allocator.
200 
Although these functions can be implemented non-intrusively using the
201 
alias constructor, if they have access to the implementation then it is
202 
possible to save storage and reduce the number of heap allocations. The
203 
newly constructed object and the _Sp_counted_* can be allocated in a single
204 
block and the standard says implementations are "encouraged, but not required,"
205 
to do so. This implementation provides additional non-standard constructors
206 
(selected with the type <code class="code">_Sp_make_shared_tag</code>) which create an
207 
object of type <code class="code">_Sp_counted_ptr_inplace</code> to hold the new object.
208 
The returned <code class="code">shared_ptr&lt;A&gt;</code> needs to know the address of the
209 
new <code class="code">A</code> object embedded in the <code class="code">_Sp_counted_ptr_inplace</code>,
210 
but it has no way to access it.
211 
This implementation uses a "covert channel" to return the address of the
212 
embedded object when <code class="code">get_deleter&lt;_Sp_make_shared_tag&gt;()</code>
213 
is called.  Users should not try to use this.
214 
As well as the extra constructors, this implementation also needs some
215 
members of _Sp_counted_deleter to be protected where they could otherwise
216 
be private.
217 
    </p></dd></dl></div></div></div><div class="sect2" title="Use"><div class="titlepage"><div><div><h3 class="title"><a id="shared_ptr.using"></a>Use</h3></div></div></div><div class="sect3" title="Examples"><div class="titlepage"><div><div><h4 class="title"><a id="id619880"></a>Examples</h4></div></div></div><p>
218 
      Examples of use can be found in the testsuite, under
219 
      <code class="filename">testsuite/tr1/2_general_utilities/shared_ptr</code>.
220 
    </p></div><div class="sect3" title="Unresolved Issues"><div class="titlepage"><div><div><h4 class="title"><a id="id653780"></a>Unresolved Issues</h4></div></div></div><p>
221 
      The resolution to C++ Standard Library issue <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#674" target="_top">674</a>,
222 
      "shared_ptr interface changes for consistency with N1856" will
223 
      need to be implemented after it is accepted into the working
224 
      paper. Issue <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#743" target="_top">743</a>
225 
      might also require changes.
226 
    </p><p>
227 
      The <span class="type">_S_single</span> policy uses atomics when used in MT
228 
      code, because it uses the same dispatcher functions that check
229 
      <code class="function">__gthread_active_p()</code>. This could be
230 
      addressed by providing template specialisations for some members
231 
      of <code class="classname">_Sp_counted_base&lt;_S_single&gt;</code>.
232 
    </p><p>
233 
      Unlike Boost, this implementation does not use separate classes
234 
      for the pointer+deleter and pointer+deleter+allocator cases in
235 
      C++0x mode, combining both into _Sp_counted_deleter and using
236 
      <code class="classname">allocator</code> when the user doesn't specify
237 
      an allocator.  If it was found to be beneficial an additional
238 
      class could easily be added.  With the current implementation,
239 
      the _Sp_counted_deleter and __shared_count constructors taking a
240 
      custom deleter but no allocator are technically redundant and
241 
      could be removed, changing callers to always specify an
242 
      allocator. If a separate pointer+deleter class was added the
243 
      __shared_count constructor would be needed, so it has been kept
244 
      for now.
245 
    </p><p>
246 
      The hack used to get the address of the managed object from
247 
      <code class="function">_Sp_counted_ptr_inplace::_M_get_deleter()</code>
248 
      is accessible to users. This could be prevented if
249 
      <code class="function">get_deleter&lt;_Sp_make_shared_tag&gt;()</code>
250 
      always returned NULL, since the hack only needs to work at a
251 
      lower level, not in the public API. This wouldn't be difficult,
252 
      but hasn't been done since there is no danger of accidental
253 
      misuse: users already know they are relying on unsupported
254 
      features if they refer to implementation details such as
255 
      _Sp_make_shared_tag.
256 
    </p><p>
257 
      tr1::_Sp_deleter could be a private member of tr1::__shared_count but it
258 
      would alter the ABI.
259 
    </p><p>
260 
      Exposing the alias constructor in TR1 mode could simplify the
261 
      *_pointer_cast functions.  Constructor could be private in TR1
262 
      mode, with the cast functions as friends.
263 
    </p></div></div><div class="sect2" title="Acknowledgments"><div class="titlepage"><div><div><h3 class="title"><a id="shared_ptr.ack"></a>Acknowledgments</h3></div></div></div><p>
264 
    The original authors of the Boost shared_ptr, which is really nice
265 
    code to work with, Peter Dimov in particular for his help and
266 
    invaluable advice on thread safety.  Phillip Jordan and Paolo
267 
    Carlini for the lock policy implementation.
268 
  </p></div><div class="bibliography" title="Bibliography"><div class="titlepage"><div><div><h3 class="title"><a id="shared_ptr.biblio"></a>Bibliography</h3></div></div></div><div class="biblioentry" title="Improving shared_ptr for C++0x, Revision 2"><a id="id678655"></a><p>[<abbr class="abbrev">
269 
      n2351
270 
    </abbr>] <span class="title"><i>
271 
      Improving shared_ptr for C++0x, Revision 2
272 
    </i>. </span><span class="subtitle">
273 
      N2351
274 
    . </span><span class="biblioid">
275 
      <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2351.htm" target="_top">
276 
      </a>
277 
    . </span></p></div><div class="biblioentry" title="C++ Standard Library Active Issues List (Revision R52)"><a id="id678679"></a><p>[<abbr class="abbrev">
278 
      n2456
279 
    </abbr>] <span class="title"><i>
280 
      C++ Standard Library Active Issues List (Revision R52)
281 
    </i>. </span><span class="subtitle">
282 
      N2456
283 
    . </span><span class="biblioid">
284 
      <a class="ulink" href="http://open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2456.html" target="_top">
285 
      </a>
286 
    . </span></p></div><div class="biblioentry" title="Working Draft, Standard for Programming Language C++"><a id="id661793"></a><p>[<abbr class="abbrev">
287 
      n2461
288 
    </abbr>] <span class="title"><i>
289 
      Working Draft, Standard for Programming Language C++
290 
    </i>. </span><span class="subtitle">
291 
      N2461
292 
    . </span><span class="biblioid">
293 
      <a class="ulink" href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2461.pdf" target="_top">
294 
      </a>
295 
    . </span></p></div><div class="biblioentry" title="Boost C++ Libraries documentation - shared_ptr class template"><a id="id612415"></a><p>[<abbr class="abbrev">
296 
      boostshared_ptr
297 
    </abbr>] <span class="title"><i>
298 
      Boost C++ Libraries documentation - shared_ptr class template
299 
    </i>. </span><span class="subtitle">
300 
      N2461
301 
    . </span><span class="biblioid">
302 
      <a class="ulink" href="http://boost.org/libs/smart_ptr/shared_ptr.htm" target="_top">shared_ptr
303 
      </a>
304 
    . </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="auto_ptr.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="memory.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="traits.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">auto_ptr </td><td width="20%" align="center"><a accesskey="h" href="../spine.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 12. Traits</td></tr></table></div></body></html>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.