basic_intrusive_ref_counter class template

Introduction

The intrusive_ref_counter class template implements a reference counter for a derived user's class that is intended to be used with intrusive_ptr. The base class has associated intrusive_ptr_add_ref and intrusive_ptr_release functions which modify the reference counter as needed and destroy the user's object when the counter drops to zero.

The class template is parameterized on DerivedT and CounterPolicyT parameters. The first parameter is the user's class that derives from intrusive_ref_counter. This type is needed in order to destroy the object correctly when there are no references to it left.

The second parameter is a policy that defines the nature of the reference counter. Boost.SmartPtr provides two such policies: thread_unsafe_counter and thread_safe_counter. The former instructs the intrusive_ref_counter base class to use a counter only suitable for a single-threaded use. Pointers to a single object that uses this kind of reference counter must not be used in different threads. The latter policy makes the reference counter thread-safe, unless the target platform doesn't support threading. Since in modern systems support for threading is common, the default counter policy is thread_safe_counter.

Synopsis

namespace boost {

  struct thread_unsafe_counter;
  struct thread_safe_counter;

  template<class DerivedT, class CounterPolicyT = thread_safe_counter>
  class intrusive_ref_counter
  {
  public:
      intrusive_ref_counter() = noexcept;
      intrusive_ref_counter(intrusive_ref_counter const & r) = noexcept;

      intrusive_ref_counter & operator=(intrusive_ref_counter const & r) noexcept;

      unsigned int use_count() const noexcept;

  protected:
      ~intrusive_ref_counter() = default;
  };

}

Members

constructors

intrusive_ref_counter();

Postconditions: use_count() == 0.

Throws: nothing.

Notes: The pointer to the constructed object is expected to be passed to intrusive_ptr constructor, assignment operator or reset() method, which would increment the reference counter.

intrusive_ref_counter(intrusive_ref_counter const &);

Postconditions: use_count() == 0.

Throws: nothing.

Notes: The pointer to the constructed object is expected to be passed to intrusive_ptr constructor, assignment operator or reset() method, which would increment the reference counter.

destructor

~intrusive_ref_counter();

Throws: nothing.

Effects: Destroys the counter object.

Notes: The destructor is protected so that the object can only be destroyed through the DerivedT class.

assignment

intrusive_ref_counter & operator=(intrusive_ref_counter const & r) noexcept;

Effects: Does nothing, reference counter is not modified.

Returns: *this.

use_count

unsigned int use_count() const noexcept;

Returns: The current value of the reference counter.

Throws: nothing.

Notes: The returned value may not be actual in multi-threaded applications.

$Date$