4.1   How does boost::intrusive_ptr not meet the needs of modern C++?

boost::intrusive_ptr<T> has had nearly the same interface since its introduction in 2001 by Peter Dimov. Furthermore, boost::intrusive_ptr has several failings in its API that cannot be changed from without breaking compatability. When constructing a boost::intrusive_ptr<T>, by default it increments the reference count. This is because of its intrusive_ref_count mixin, which starts with a reference count of 0 when it is default constructed. Out of all the libraries I tried to look at, this was the one instance where an object required it be incremented after construction. This should be the exception, and this proposal rectifies this with its equivalent mixins, which start with a reference count of 1.

Additionally, boost::intrusive_ptr does not have the ability to "overload" its pointer type member, requiring some additional work when interfacing with C APIs (e.g., boost::intrusive_ptr<decltype(*declval<cl_mem>())>).

Furthermore, boost::intrusive_ptr relies on ADL calls of two functions: intrusive_add_ref and intrusive_release. While this approach is fine in most cases, it does remove the ability to easily "swap out" the approach used when incrementing or decrementing the reference count (e.g., logging when reference count reaches 0, but not when in a production environment). This approach also uses terms found in Microsoft's COM. While this isn't an issue per se, it would be odd to have functions with those names found in the standard.

4.2   Is retain_ptr atomic?

retain_ptr<T> is only atomic in its reference count increment and decrement if the object it manages is itself atomic in its reference count operations.

4.3   Why is it called retain_ptr and not intrusive_ptr?

retain_ptr<T, R> diverges from the design of boost::intrusive_ptr<T>. It was decided to change the name so as to not cause assumptions of retain_ptr<T, R> interface and behavior.

Some additional names that might be considered (for bikeshedding) are:

• extend_ptr
• counted_ptr
• borrow_ptr
• mutual_ptr
• joint_ptr

Comedy Option:

• auto_ptr

4.4   Does retain_ptr support allocators?

retain_ptr itself does not support allocators, however the object whose lifetime it extends can.

4.5   Can retain_ptr be constexpr?

Possibly, however the author questions the usefulness for a constexpr capable intrusive smart pointer, as most use cases are intended for migrating existing non-constexpr interfaces, and for types that simply cannot be constexpr, such as incomplete types and polymorphic classes.

4.6   Why does retain_ptr use detach instead of release like unique_ptr?

retain_ptr<T> diverges from common smart pointer functions that release ownership of their managed object via a function release(), which returns the object in its current state, and places the retain_ptr into an empty state. retain_ptr<T> opts to use the name detach() for semantic reasons. Many objects that might be managed by retain_ptr<T> tend to use a function or operation named release to decrement the internal reference count. To reduce confusion for implementers and those curious enough to look under the hood, a different name was chosen (i.e., detach()). This name was also used by boost::intrusive_ptr.

A retain_ptr<T> does not own the object is manages. Rather it is extending ownership. When we use detach, we aren't telling the retain_ptr<T> to release ownership to the caller. Instead we are expressing our desire for the retain_ptr<T> to detach its management of the object it stores. Other possible names for detach() that could be considered are disengage, discard, and withdraw.

4.7   Why provide retain_t?

retain_t (and its instance retain) are currently used to represent the case where a retain_ptr needs to extend (i.e., retain) a pointer to an object. This mostly comes into play when interacting with APIs that return a borrowed reference to an object without incrementing its reference count to begin with. Additionally, an enum class retain : bool { no, yes } would technically be possible, but this would be the first time such an API is placed into the standard library.

The name of this type is available for bikeshedding however. Some other less elegant names include:

• retain_element_t
• extend_element_t
• retainobj_t
• extendobj_t
• extend_t

4.8   Can retain_traits store state?

No. Any important state regarding the object or how it is retained, can be stored in the object itself. For example, if the reference count needs to be external from the object, std::shared_ptr would be a better choice.

4.9   Why not just wrap a unique_ptr with a custom deleter?

This is an extraordinary amount of code that would not be guaranteed to have a homogenous interface across different libraries and implementations. For example, using retain_ptr with an OpenCL context object (without checking for errors in both implementations) is as simple as:

 1 struct context_traits {
 2   using pointer = cl_context;
 3   static void increment (pointer p) { clRetainContext(p); }
 4   static void decrement (pointer p) { clReleaseContext(p); }
 5 };
 6 
 7 struct context {
 8   using handle_type = retain_ptr<cl_context, context_traits>;
 9   using pointer = handle_type::pointer;
10   context (pointer p, retain_t) : handle(p, retain) { }
11   context (pointer p) : handle(p) { }
12 private:
13   handle_type handle;
14 };

Using the unique_ptr approach requires more effort. In this case, it is twice as long to get the same functionality:

 1 struct context_deleter {
 2   using pointer = cl_context;
 3   void increment (pointer p) const {
 4     if (p) { clRetainContext(p); } // retain_ptr checks for null for us
 5   }
 6   void operator () (pointer p) const { clReleaseContext(p); }
 7 };
 8 
 9 struct retain_t { };
10 constexpr retain_t retain { };
11 
12 struct context {
13   using handle_type = unique_ptr<cl_context, context_deleter>;
14   using pointer = handle_type::pointer;
15 
16   context (pointer p, retain_t) :
17     context(p)
18   { handle.get_deleter().increment(handle.get()); }
19 
20   context (pointer p) : handle(p) { }
21 
22   context (context const& that) :
23     handle(that.handle.get())
24   { handle.get_deleter().increment(handle.get()) }
25 
26   context& operator = (context const& that) {
27     context(that.handle.get(), retain).swap(*this);
28     return *this;
29   }
30 
31 private:
32   handle_type handle;
33 };

As we can see, using retain_ptr<T> saves effort, allowing us in most cases to simply rely on the "rule of zero" for constructor management. It will also not confuse/terrify potential maintainers of code bases where objects construct a unique_ptr with the raw pointer of another (and ownership is not transferred).

5.1   atomic_reference_count<T> and reference_count<T>

atomic_reference_count<T> and reference_count<T> are mixin types, provided for user defined types that simply rely on new and delete to have their lifetime extended by retain_ptr. The template parameter T is intended to be the type deriving from atomic_reference_count or reference_count (a.k.a. the curiously repeating template pattern, CRTP).

template <class T>
 struct atomic_reference_count {
   friend retain_traits<T>;
 protected:
   atomic_reference_count () = default;
 private:
   atomic<uint_least64_t> count { 1 }; // provided for exposition
 };

 template <class T>
 struct reference_count {
   friend retain_traits<T>;
 protected:
   reference_count () = default;
 private:
   uint_least64_t count { 1 }; // provided for exposition
 };

5.2   retain_t

retain_t is a sentinel type, with a constexpr instance retain.

namespace std {
  struct retain_element_t { constexpr retain_element_t () = default; }
  constexpr retain_t retain { };
}

5.3   retain_traits<T>

The class template retain_traits serves as the default traits object for the class template retain_ptr. Unless retain_traits is specialized for a specific type, the template parameter T must inherit from either atomic_reference_count<T> or reference_count<T>. In the event that retain_traits is specialized for a type, the template parameter T may be an incomplete type.

namespace std {
  template <class T> struct retain_traits {
    static void increment (atomic_reference_count<T>*) noexcept;
    static void decrement (atomic_reference_count<T>*) noexcept;
    static long use_count (atomic_reference_count<T>*) noexcept;

    static void increment (reference_count<T>*) noexcept;
    static void decrement (reference_count<T>*) noexcept;
    static long use_count (reference_count<T>*) noexcept;
  };
}

static void increment (atomic_reference_count<T>* ptr) noexcept;

effects:	Increments the internal reference count for ptr with memory_order_acq_rel
postcondition:	ptr->count has been incremented by 1.

static void decrement (atomic_reference_count<T>* ptr) noexcept;

effects:	Decrements the internal reference count for ptr with memory_order_acq_rel. If the internal reference count of ptr reaches 0, it is disposed of via delete.

static long use_count (atomic_reference_count<T>* ptr) noexcept;

returns:	The internal reference count for ptr with memory_order_acquire.

static void increment (reference_count<T>* ptr) noexcept;

effects:	Increments the internal reference count for ptr by 1.

static void decrement (reference_count<T>* ptr) noexcept;

effects:	Decrements the internal reference for ptr by 1. If the count reaches 0, ptr is disposed of via delete.

static long use_count (reference_count<T>* ptr) noexcept;

returns:	The reference count for ptr.

5.4   retain_ptr<T, R>

The default type for the template parameter R is retain_traits. A client supplied template argument R shall be an object with non-member functions for which, given a ptr of type unique_ptr<T, R>::pointer, the expressions R::increment(ptr) and R::decrement(ptr) are valid and has the effect of retaining or disposing of the pointer as appropriate for that retainer.

If the qualified-id R::pointer is valid and denotes a type, then retain_ptr<T, R>::pointer shall be synonymous with R::pointer. Otherwise retain_ptr<T, R>::pointer shall be a synonym for element_type*. The type retain_ptr<T, R>::pointer shall satisfy the requirements of NullablePointer.

template <class T, class R=retain_traits<T>>
struct retain_ptr {
  using element_type = T;
  using traits_type = R;
  using pointer = /* see below */

  retain_ptr (pointer, retain_t) noexcept(/* see below */);
  explicit retain_ptr (pointer) noexcept;
  retain_ptr (nullptr_t) noexcept : retain_ptr() { }

  retain_ptr (retain_ptr const&) noexcept(/* see below */);
  retain_ptr (retain_ptr&&) noexcept;
  retain_ptr () noexcept;
  ~retain_ptr () noexcept(/* see below */);

  retain_ptr& operator = (retain_ptr const&) noexcept(/* see below */);
  retain_ptr& operator = (retain&&) noexcept;

  retain_ptr& operator = (nullptr_t) noexcept;

  void swap (retain_ptr&) noexcept;

  explicit operator pointer () const noexcept;
  explicit operator bool () const noexcept;

  element_type& operator * () const noexcept;
  pointer operator -> () const noexcept;
  pointer get () const noexcept;

  long use_count () const noexcept(/* see below */);
  bool unique () const noexcept(/* see below */);

  [[nodiscard]] pointer detach () noexcept;

  void reset (pointer, retain_t) noexcept(/* see below */);
  void reset (pointer p = pointer { }) noexcept(/* see below */);
};

template <class T, class R>
void swap (retain_ptr<T, R>&, retain_ptr<T, R>&) noexcept;

template <class T, class R>
bool operator == (retain_ptr<T, R> const&, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator != (retain_ptr<T, R> const&, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator >= (retain_ptr<T, R> const&, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator <= (retain_ptr<T, R> const&, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator > (retain_ptr<T, R> const&, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator < (retain_ptr<T, R> const&, retain_ptr<T, R> const&) noexcept;

template <class T, class R>
bool operator == (retain_ptr<T, R> const&, nullptr_t) noexcept;
template <class T, class R>
bool operator != (retain_ptr<T, R> const&, nullptr_t) noexcept;
template <class T, class R>
bool operator >= (retain_ptr<T, R> const&, nullptr_t) noexcept;
template <class T, class R>
bool operator <= (retain_ptr<T, R> const&, nullptr_t) noexcept;
template <class T, class R>
bool operator > (retain_ptr<T, R> const&, nullptr_t) noexcept;
template <class T, class R>
bool operator < (retain_ptr<T, R> const&, nullptr_t) noexcept;

template <class T, class R>
bool operator == (nullptr_t, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator != (nullptr_t, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator >= (nullptr_t, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator <= (nullptr_t, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator > (nullptr_t, retain_ptr<T, R> const&) noexcept;
template <class T, class R>
bool operator < (nullptr_t, retain_ptr<T, R> const&) noexcept;

6.1   Futures

template <class T>
struct shared_state : atomic_reference_counter {
  bool empty () const noexcept { return get_if<0>(this->obj); }
  T get () const noexcept(false) {
    if (auto ptr = get_if<1>(this->obj)) { return move(*ptr); }
    rethrow_exception(get<2>(this->obj));
  }
  variant<monostate, T, exception_ptr> obj;
};

template <class T>
struct promise {
  using value_type = T;

  future<T> get_future () const noexcept { return this->state; }

  template <class U>
  void set_value (U&& value) {
    this->state.template emplace<1>(forward<U>(value));
  }

  void set_exception (exception_ptr ptr) noexcept {
    this->state.template emplace<2>(ptr);
  }

private:
  retain_ptr<shared_state<T>> state { new shared_state<T>() };
};

template <class T>
struct future {
  friend promise<T>;

  bool valid () const noexcept { return this->state->empty(); }
  T get () noexcept(false) {
    if (not this->valid()) { throw future_error(future_errc::no_state); }
    return this->state->get();
  }

private:
  future (retain_ptr<shared_state<T>> const& state) : state(state) { }
  retain_ptr<shared_state<T>> state;
};