diff --git a/doc/smart_ptr/intrusive_ref_counter.adoc b/doc/smart_ptr/intrusive_ref_counter.adoc index 61f9ed6..091f9cd 100644 --- a/doc/smart_ptr/intrusive_ref_counter.adoc +++ b/doc/smart_ptr/intrusive_ref_counter.adoc @@ -1,5 +1,6 @@ //// Copyright 2017 Peter Dimov +Copyright 2013 Andrey Semashev Distributed under the Boost Software License, Version 1.0. @@ -13,3 +14,98 @@ http://www.boost.org/LICENSE_1_0.txt :toc-title: :idprefix: intrusive_ref_counter_ +## Description + +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 `Derived` and `CounterPolicy` +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. The library 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 + +`intrusive_ref_counter` is defined in +``. + +``` +namespace boost { + struct thread_unsafe_counter; + struct thread_safe_counter; + + template + class intrusive_ref_counter { + public: + intrusive_ref_counter() noexcept; + intrusive_ref_counter(const intrusive_ref_counter& v) noexcept; + + intrusive_ref_counter& operator=(const intrusive_ref_counter& v) noexcept; + + unsigned int use_count() const noexcept; + + protected: + ~intrusive_ref_counter() = default; + }; +} +``` + +## Members + +### Constructors + +``` +intrusive_ref_counter() noexcept; +``` +:: +``` +intrusive_ref_counter(const intrusive_ref_counter&) noexcept; +``` +:: +Postconditions::: `use_count() == 0`. + +NOTE: 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(); +``` +:: +Effects::: Destroys the counter object. + +NOTE: The destructor is protected so that the object can only be destroyed +through the `Derived` class. + +### Assignment + +``` +intrusive_ref_counter& operator=(const intrusive_ref_counter& v) noexcept; +``` +:: +Effects::: Does nothing, reference counter is not modified. + +### use_count + +``` +unsigned int use_count() const noexcept; +``` +:: +Returns::: The current value of the reference counter. + +NOTE: The returned value may not be actual in multi-threaded applications.