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

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3     <head>
   4         <title>intrusive_ref_counter</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">basic_intrusive_ref_counter 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         </p>
  15         <h2><a name="Introduction">Introduction</a></h2>
  16         <p>The <STRONG>intrusive_ref_counter</STRONG> class template implements a reference counter for a derived
  17             user's class that is intended to be used with <STRONG><a href="intrusive_ptr.html">intrusive_ptr</a></STRONG>.
  18             The base class has associated <STRONG>intrusive_ptr_add_ref</STRONG> and <STRONG>intrusive_ptr_release</STRONG> functions
  19             which modify the reference counter as needed and destroy the user's object when the counter drops to zero.</p>
  20         <p>The class template is parameterized on <STRONG>DerivedT</STRONG> and <STRONG>CounterPolicyT</STRONG> parameters.
  21             The first parameter is the user's class that derives from <STRONG>intrusive_ref_counter</STRONG>. This type
  22             is needed in order to destroy the object correctly when there are no references to it left.</p>
  23         <p>The second parameter is a policy that defines the nature of the reference counter.
  24             Boost.SmartPtr provides two such policies: <STRONG>thread_unsafe_counter</STRONG> and <STRONG>thread_safe_counter</STRONG>. The former
  25             instructs the <STRONG>intrusive_ref_counter</STRONG> base class to use a counter only suitable for a single-threaded use.
  26             Pointers to a single object that uses this kind of reference counter must not be used in different threads. The latter policy
  27             makes the reference counter thread-safe, unless the target platform doesn't support threading. Since in modern systems support for
  28             threading is common, the default counter policy is <STRONG>thread_safe_counter</STRONG>.</p>
  29         <h2><a name="Synopsis">Synopsis</a></h2>
  30         <pre>namespace boost {
  31
  32   struct thread_unsafe_counter;
  33   struct thread_safe_counter;
  34
  35   template&lt;class DerivedT, class CounterPolicyT = thread_safe_counter&gt;
  36   class intrusive_ref_counter
  37   {
  38   public:
  39       <A href="#constructors" >intrusive_ref_counter</A>() = noexcept;
  40       <A href="#constructors" >intrusive_ref_counter</A>(intrusive_ref_counter const &amp; r) = noexcept;
  41
  42       intrusive_ref_counter &amp; <A href="#assignment" >operator=</A>(intrusive_ref_counter const &amp; r) noexcept;
  43
  44       unsigned int <a href="#use_count" >use_count</a>() const noexcept;
  45
  46   protected:
  47       <A href="#destructor" >~intrusive_ref_counter</A>() = default;
  48   };
  49
  50 }</pre>
  51         <h2><a name="Members">Members</a></h2>
  52         <h3><a name="constructors">constructors</a></h3>
  53         <pre>intrusive_ref_counter();</pre>
  54         <blockquote>
  55             <p><b>Postconditions:</b> <code>use_count() == 0</code>.</p>
  56             <p><b>Throws:</b> nothing.</p>
  57             <P><B>Notes:</B> The pointer to the constructed object is expected to be passed to <STRONG>intrusive_ptr</STRONG>
  58             constructor, assignment operator or <STRONG>reset()</STRONG> method, which would increment the reference counter.</P>
  59         </blockquote>
  60         <pre>intrusive_ref_counter(intrusive_ref_counter const &amp;);</pre>
  61         <blockquote>
  62             <p><b>Postconditions:</b> <code>use_count() == 0</code>.</p>
  63             <p><b>Throws:</b> nothing.</p>
  64             <P><B>Notes:</B> The pointer to the constructed object is expected to be passed to <STRONG>intrusive_ptr</STRONG>
  65             constructor, assignment operator or <STRONG>reset()</STRONG> method, which would increment the reference counter.</P>
  66         </blockquote>
  67         <h3><a name="destructor">destructor</a></h3>
  68         <pre>~intrusive_ref_counter();</pre>
  69         <BLOCKQUOTE>
  70             <p><b>Throws:</b> nothing.</p>
  71             <P><B>Effects:</B> Destroys the counter object.</P>
  72             <P><B>Notes:</B> The destructor is protected so that the object can only be destroyed through the <STRONG>DerivedT</STRONG> class.</P>
  73         </BLOCKQUOTE>
  74         <H3><a name="assignment">assignment</a></H3>
  75         <pre>intrusive_ref_counter &amp; operator=(intrusive_ref_counter const &amp; r) noexcept;</pre>
  76         <BLOCKQUOTE>
  77             <P><B>Effects:</B> Does nothing, reference counter is not modified.</P>
  78             <P><B>Returns:</B> <code>*this</code>.</P>
  79         </BLOCKQUOTE>
  80         <H3><a name="use_count">use_count</a></H3>
  81         <pre>unsigned int use_count() const noexcept;</pre>
  82         <BLOCKQUOTE>
  83             <p><b>Returns:</b> The current value of the reference counter.</p>
  84             <p><b>Throws:</b> nothing.</p>
  85             <P><B>Notes:</B> The returned value may not be actual in multi-threaded applications.</P>
  86         </BLOCKQUOTE>
  87         <hr>
  88         <p>$Date$</p>
  89         <p>
  90             <small>Copyright &copy; 2013 Andrey Semashev. Distributed under the Boost Software License, Version
  91             1.0. See accompanying file <A href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</A> or
  92             copy at <A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>.</small></p>
  93     </body>
  94 </html>