ceph/src/boost/libs/smart_ptr/intrusive_ptr.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3     <head>
   4         <title>intrusive_ptr</title>
   5         <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6     </head>
   7     <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
   8         <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
   9             width="277" align="middle" border="0">intrusive_ptr class template</h1>
  10         <p>
  11             <a href="#Introduction">Introduction</a><br>
  12             <a href="#Synopsis">Synopsis</a><br>
  13             <a href="#Members">Members</a><br>
  14             <a href="#functions">Free Functions</a><br>
  15         </p>
  16         <h2><a name="Introduction">Introduction</a></h2>
  17         <p>The <code>intrusive_ptr</code> class template stores a pointer to an object with an
  18             embedded reference count. Every new <code>intrusive_ptr</code> instance increments
  19             the reference count by using an unqualified call to the function <code>intrusive_ptr_add_ref</code>,
  20             passing it the pointer as an argument. Similarly, when an <code>intrusive_ptr</code>
  21             is destroyed, it calls <code>intrusive_ptr_release</code>; this function is
  22             responsible for destroying the object when its reference count drops to zero.
  23             The user is expected to provide suitable definitions of these two functions. On
  24             compilers that support argument-dependent lookup, <code>intrusive_ptr_add_ref</code>
  25             and <code>intrusive_ptr_release</code> should be defined in the namespace
  26             that corresponds to their parameter; otherwise, the definitions need to go in
  27             namespace <code>boost</code>. The library provides a helper base class template
  28             <code><a href="intrusive_ref_counter.html">intrusive_ref_counter</a></code> which may
  29             help adding support for <code>intrusive_ptr</code> to user types.</p>
  30         <p>The class template is parameterized on <code>T</code>, the type of the object pointed
  31             to. <code>intrusive_ptr&lt;T&gt;</code> can be implicitly converted to <code>intrusive_ptr&lt;U&gt;</code>
  32             whenever <code>T*</code> can be implicitly converted to <code>U*</code>.</p>
  33         <p>The main reasons to use <code>intrusive_ptr</code> are:</p>
  34         <ul>
  35             <li>
  36             Some existing frameworks or OSes provide objects with embedded reference
  37             counts;</li>
  38             <li>
  39                 The memory footprint of <code>intrusive_ptr</code>
  40             is the same as the corresponding raw pointer;</li>
  41             <li>
  42                 <code>intrusive_ptr&lt;T&gt;</code> can be constructed from an arbitrary
  43                 raw pointer of type <code>T *</code>.</li></ul>
  44         <p>As a general rule, if it isn't obvious whether <code>intrusive_ptr</code> better
  45             fits your needs than <code>shared_ptr</code>, try a <code>shared_ptr</code>-based
  46             design first.</p>
  47         <h2><a name="Synopsis">Synopsis</a></h2>
  48         <pre>namespace boost {
  49
  50   template&lt;class T&gt; class intrusive_ptr {
  51
  52     public:
  53
  54       typedef T <a href="#element_type" >element_type</a>;
  55
  56       <a href="#constructors" >intrusive_ptr</a>(); // never throws
  57       <a href="#constructors" >intrusive_ptr</a>(T * p, bool add_ref = true);
  58
  59       <a href="#constructors" >intrusive_ptr</a>(intrusive_ptr const &amp; r);
  60       template&lt;class Y&gt; <a href="#constructors" >intrusive_ptr</a>(intrusive_ptr&lt;Y&gt; const &amp; r);
  61
  62       <a href="#destructor" >~intrusive_ptr</a>();
  63
  64       intrusive_ptr &amp; <a href="#assignment" >operator=</a>(intrusive_ptr const &amp; r);
  65       template&lt;class Y&gt; intrusive_ptr &amp; <a href="#assignment" >operator=</a>(intrusive_ptr&lt;Y&gt; const &amp; r);
  66       intrusive_ptr &amp; <a href="#assignment" >operator=</a>(T * r);
  67
  68       void <a href="#reset" >reset</a>();
  69       void <a href="#reset" >reset</a>(T * r);
  70       void <a href="#reset" >reset</a>(T * r, bool add_ref);
  71
  72       T &amp; <a href="#indirection" >operator*</a>() const; // never throws
  73       T * <a href="#indirection" >operator-&gt;</a>() const; // never throws
  74       T * <a href="#get" >get</a>() const; // never throws
  75       T * <a href="#detach" >detach</a>(); // never throws
  76
  77       operator <a href="#conversions" ><i>unspecified-bool-type</i></a>() const; // never throws
  78
  79       void <a href="#swap" >swap</a>(intrusive_ptr &amp; b); // never throws
  80   };
  81
  82   template&lt;class T, class U&gt;
  83     bool <a href="#comparison" >operator==</a>(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws
  84
  85   template&lt;class T, class U&gt;
  86     bool <a href="#comparison" >operator!=</a>(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws
  87
  88   template&lt;class T&gt;
  89     bool <a href="#comparison" >operator==</a>(intrusive_ptr&lt;T&gt; const &amp; a, T * b); // never throws
  90
  91   template&lt;class T&gt;
  92     bool <a href="#comparison" >operator!=</a>(intrusive_ptr&lt;T&gt; const &amp; a, T * b); // never throws
  93
  94   template&lt;class T&gt;
  95     bool <a href="#comparison" >operator==</a>(T * a, intrusive_ptr&lt;T&gt; const &amp; b); // never throws
  96
  97   template&lt;class T&gt;
  98     bool <a href="#comparison" >operator!=</a>(T * a, intrusive_ptr&lt;T&gt; const &amp; b); // never throws
  99
 100   template&lt;class T, class U&gt;
 101     bool <a href="#comparison" >operator&lt;</a>(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws
 102
 103   template&lt;class T&gt; void <a href="#free-swap" >swap</a>(intrusive_ptr&lt;T&gt; &amp; a, intrusive_ptr&lt;T&gt; &amp; b); // never throws
 104
 105   template&lt;class T&gt; T * <a href="#get_pointer" >get_pointer</a>(intrusive_ptr&lt;T&gt; const &amp; p); // never throws
 106
 107   template&lt;class T, class U&gt;
 108     intrusive_ptr&lt;T&gt; <a href="#static_pointer_cast" >static_pointer_cast</a>(intrusive_ptr&lt;U&gt; const &amp; r); // never throws
 109
 110   template&lt;class T, class U&gt;
 111     intrusive_ptr&lt;T&gt; <a href="#const_pointer_cast" >const_pointer_cast</a>(intrusive_ptr&lt;U&gt; const &amp; r); // never throws
 112
 113   template&lt;class T, class U&gt;
 114     intrusive_ptr&lt;T&gt; <a href="#dynamic_pointer_cast" >dynamic_pointer_cast</a>(intrusive_ptr&lt;U&gt; const &amp; r); // never throws
 115
 116   template&lt;class E, class T, class Y&gt;
 117     std::basic_ostream&lt;E, T&gt; &amp; <a href="#insertion-operator" >operator&lt;&lt;</a> (std::basic_ostream&lt;E, T&gt; &amp; os, intrusive_ptr&lt;Y&gt; const &amp; p);
 118
 119 }</pre>
 120         <h2><a name="Members">Members</a></h2>
 121         <h3><a name="element_type">element_type</a></h3>
 122         <pre>typedef T element_type;</pre>
 123         <blockquote>
 124             <p>Provides the type of the template parameter <code>T</code>.</p>
 125         </blockquote>
 126         <h3><a name="constructors">constructors</a></h3>
 127         <pre>intrusive_ptr(); // never throws</pre>
 128         <blockquote>
 129             <p><b>Postconditions:</b> <code>get() == 0</code>.</p>
 130             <p><b>Throws:</b> nothing.</p>
 131         </blockquote>
 132         <pre>intrusive_ptr(T * p, bool add_ref = true);</pre>
 133         <blockquote>
 134             <p><b>Effects:</b> <code>if(p != 0 &amp;&amp; add_ref) intrusive_ptr_add_ref(p);</code>.</p>
 135             <p><b>Postconditions:</b> <code>get() == p</code>.</p>
 136         </blockquote>
 137         <pre>intrusive_ptr(intrusive_ptr const &amp; r);
 138 template&lt;class Y&gt; intrusive_ptr(intrusive_ptr&lt;Y&gt; const &amp; r);</pre>
 139         <blockquote>
 140             <p><b>Effects:</b> <code>if(r.get() != 0) intrusive_ptr_add_ref(r.get());</code>.</p>
 141             <p><b>Postconditions:</b> <code>get() == r.get()</code>.</p>
 142         </blockquote>
 143         <h3><a name="destructor">destructor</a></h3>
 144         <pre>~intrusive_ptr();</pre>
 145         <blockquote>
 146             <p><b>Effects:</b> <code>if(get() != 0) intrusive_ptr_release(get());</code>.</p>
 147         </blockquote>
 148         <h3><a name="assignment">assignment</a></h3>
 149         <pre>intrusive_ptr &amp; operator=(intrusive_ptr const &amp; r);
 150 template&lt;class Y&gt; intrusive_ptr &amp; operator=(intrusive_ptr&lt;Y&gt; const &amp; r);
 151 intrusive_ptr &amp; operator=(T * r);</pre>
 152         <blockquote>
 153             <p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
 154             <p><b>Returns:</b> <code>*this</code>.</p>
 155         </blockquote>
 156         <h3><a name="reset">reset</a></h3>
 157         <pre>void reset();</pre>
 158         <blockquote>
 159             <p><b>Effects:</b> Equivalent to <code>intrusive_ptr().swap(*this)</code>.</p>
 160         </blockquote>
 161         <pre>void reset(T * r);</pre>
 162         <blockquote>
 163             <p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r).swap(*this)</code>.</p>
 164         </blockquote>
 165         <pre>void reset(T * r, bool add_ref);</pre>
 166         <blockquote>
 167             <p><b>Effects:</b> Equivalent to <code>intrusive_ptr(r, add_ref).swap(*this)</code>.</p>
 168         </blockquote>
 169         <h3><a name="indirection">indirection</a></h3>
 170         <pre>T &amp; operator*() const; // never throws</pre>
 171         <blockquote>
 172             <p><b>Requirements:</b> <code>get() != 0</code>.</p>
 173             <p><b>Returns:</b> <code>*get()</code>.</p>
 174             <p><b>Throws:</b> nothing.</p>
 175         </blockquote>
 176         <pre>T * operator-&gt;() const; // never throws</pre>
 177         <blockquote>
 178             <p><b>Requirements:</b> <code>get() != 0</code>.</p>
 179             <p><b>Returns:</b> <code>get()</code>.</p>
 180             <p><b>Throws:</b> nothing.</p>
 181         </blockquote>
 182         <h3><a name="get">get</a></h3>
 183         <pre>T * get() const; // never throws</pre>
 184         <blockquote>
 185             <p><b>Returns:</b> the stored pointer.</p>
 186             <p><b>Throws:</b> nothing.</p>
 187         </blockquote>
 188         <h3><a name="detach">detach</a></h3>
 189         <pre>T * detach(); // never throws</pre>
 190         <blockquote>
 191             <p><b>Returns:</b> the stored pointer.</p>
 192             <p><b>Throws:</b> nothing.</p>
 193             <p><b>Postconditions:</b> <code>get() == 0</code>.</p>
 194             <p><b>Notes:</b> The returned pointer has an elevated reference count. This
 195                 allows conversion of an <code>intrusive_ptr</code> back to a raw pointer,
 196                 without the performance overhead of acquiring and dropping an extra
 197                 reference. It can be viewed as the complement of the
 198                 non-reference-incrementing constructor.</p>
 199             <p><b>Caution:</b> Using <code>detach</code> escapes the safety of automatic
 200                 reference counting provided by <code>intrusive_ptr</code>. It should
 201                 by used only where strictly necessary (such as when interfacing to an
 202                 existing API), and when the implications are thoroughly understood.</p>
 203         </blockquote>
 204         <h3><a name="conversions">conversions</a></h3>
 205         <pre>operator <i>unspecified-bool-type</i> () const; // never throws</pre>
 206         <blockquote>
 207             <p><b>Returns:</b> an unspecified value that, when used in boolean contexts, is
 208                 equivalent to <code>get() != 0</code>.</p>
 209             <p><b>Throws:</b> nothing.</p>
 210             <p><b>Notes:</b> This conversion operator allows <code>intrusive_ptr</code> objects to be
 211                 used in boolean contexts, like <code>if (p &amp;&amp; p-&gt;valid()) {}</code>.
 212                 The actual target type is typically a pointer to a member function, avoiding
 213                 many of the implicit conversion pitfalls.</p>
 214         </blockquote>
 215         <h3><a name="swap">swap</a></h3>
 216         <pre>void swap(intrusive_ptr &amp; b); // never throws</pre>
 217         <blockquote>
 218             <p><b>Effects:</b> Exchanges the contents of the two smart pointers.</p>
 219             <p><b>Throws:</b> nothing.</p>
 220         </blockquote>
 221         <h2><a name="functions">Free Functions</a></h2>
 222         <h3><a name="comparison">comparison</a></h3>
 223         <pre>template&lt;class T, class U&gt;
 224   bool operator==(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
 225         <blockquote>
 226             <p><b>Returns:</b> <code>a.get() == b.get()</code>.</p>
 227             <p><b>Throws:</b> nothing.</p>
 228         </blockquote>
 229         <pre>template&lt;class T, class U&gt;
 230   bool operator!=(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
 231         <blockquote>
 232             <p><b>Returns:</b> <code>a.get() != b.get()</code>.</p>
 233             <p><b>Throws:</b> nothing.</p>
 234         </blockquote>
 235         <pre>template&lt;class T, class U&gt;
 236   bool operator==(intrusive_ptr&lt;T&gt; const &amp; a, U * b); // never throws</pre>
 237         <blockquote>
 238             <p><b>Returns:</b> <code>a.get() == b</code>.</p>
 239             <p><b>Throws:</b> nothing.</p>
 240         </blockquote>
 241         <pre>template&lt;class T, class U&gt;
 242   bool operator!=(intrusive_ptr&lt;T&gt; const &amp; a, U * b); // never throws</pre>
 243         <blockquote>
 244             <p><b>Returns:</b> <code>a.get() != b</code>.</p>
 245             <p><b>Throws:</b> nothing.</p>
 246         </blockquote>
 247         <pre>template&lt;class T, class U&gt;
 248   bool operator==(T * a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
 249         <blockquote>
 250             <p><b>Returns:</b> <code>a == b.get()</code>.</p>
 251             <p><b>Throws:</b> nothing.</p>
 252         </blockquote>
 253         <pre>template&lt;class T, class U&gt;
 254   bool operator!=(T * a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
 255         <blockquote>
 256             <p><b>Returns:</b> <code>a != b.get()</code>.</p>
 257             <p><b>Throws:</b> nothing.</p>
 258         </blockquote>
 259         <pre>template&lt;class T, class U&gt;
 260   bool operator&lt;(intrusive_ptr&lt;T&gt; const &amp; a, intrusive_ptr&lt;U&gt; const &amp; b); // never throws</pre>
 261         <blockquote>
 262             <p><b>Returns:</b> <code>std::less&lt;T *&gt;()(a.get(), b.get())</code>.</p>
 263             <p><b>Throws:</b> nothing.</p>
 264             <p><b>Notes:</b> Allows <code>intrusive_ptr</code> objects to be used as keys
 265                 in associative containers.</p>
 266         </blockquote>
 267         <h3><a name="free-swap">swap</a></h3>
 268         <pre>template&lt;class T&gt;
 269   void swap(intrusive_ptr&lt;T&gt; &amp; a, intrusive_ptr&lt;T&gt; &amp; b); // never throws</pre>
 270         <blockquote>
 271             <p><b>Effects:</b> Equivalent to <code>a.swap(b)</code>.</p>
 272             <p><b>Throws:</b> nothing.</p>
 273             <p><b>Notes:</b> Matches the interface of <code>std::swap</code>. Provided as an aid to
 274                 generic programming.</p>
 275         </blockquote>
 276         <h3><a name="get_pointer">get_pointer</a></h3>
 277         <pre>template&lt;class T&gt;
 278   T * get_pointer(intrusive_ptr&lt;T&gt; const &amp; p); // never throws</pre>
 279         <blockquote>
 280             <p><b>Returns:</b> <code>p.get()</code>.</p>
 281             <p><b>Throws:</b> nothing.</p>
 282             <p><b>Notes:</b> Provided as an aid to generic programming. Used by <a href="../bind/mem_fn.html">
 283                     mem_fn</a>.</p>
 284         </blockquote>
 285         <h3><a name="static_pointer_cast">static_pointer_cast</a></h3>
 286         <pre>template&lt;class T, class U&gt;
 287   intrusive_ptr&lt;T&gt; static_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r); // never throws</pre>
 288         <blockquote>
 289             <p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(static_cast&lt;T*&gt;(r.get()))</code>.</p>
 290             <p><b>Throws:</b> nothing.</p>
 291         </blockquote>
 292         <h3><a name="const_pointer_cast">const_pointer_cast</a></h3>
 293         <pre>template&lt;class T, class U&gt;
 294   intrusive_ptr&lt;T&gt; const_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r); // never throws</pre>
 295         <blockquote>
 296             <p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(const_cast&lt;T*&gt;(r.get()))</code>.</p>
 297             <p><b>Throws:</b> nothing.</p>
 298         </blockquote>
 299         <h3><a name="dynamic_pointer_cast">dynamic_pointer_cast</a></h3>
 300         <pre>template&lt;class T, class U&gt;
 301   intrusive_ptr&lt;T&gt; dynamic_pointer_cast(intrusive_ptr&lt;U&gt; const &amp; r);</pre>
 302         <blockquote>
 303             <p><b>Returns:</b> <code>intrusive_ptr&lt;T&gt;(dynamic_cast&lt;T*&gt;(r.get()))</code>.</p>
 304             <p><b>Throws:</b> nothing.</p>
 305         </blockquote>
 306         <h3><a name="insertion-operator">operator&lt;&lt;</a></h3>
 307         <pre>template&lt;class E, class T, class Y&gt;
 308     std::basic_ostream&lt;E, T&gt; &amp; operator&lt;&lt; (std::basic_ostream&lt;E, T&gt; &amp; os, intrusive_ptr&lt;Y&gt; const &amp; p);</pre>
 309         <blockquote>
 310             <p><b>Effects:</b> <code>os &lt;&lt; p.get();</code>.</p>
 311             <p><b>Returns:</b> <code>os</code>.</p>
 312         </blockquote>
 313         <hr>
 314         <p>$Date$</p>
 315         <p>
 316             <small>Copyright &copy; 2003-2005, 2013 Peter Dimov. Distributed under the Boost Software License, Version
 317             1.0. See accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
 318             copy at <a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>.</small></p>
 319     </body>
 320 </html>