rc.hpp

Go to the documentation of this file.

//    OpenVPN -- An application to securely tunnel IP networks
//               over a single port, with support for SSL/TLS-based
//               session authentication and key exchange,
//               packet encryption, packet authentication, and
//               packet compression.
//
//    Copyright (C) 2012- OpenVPN Inc.
//
//    SPDX-License-Identifier: MPL-2.0 OR AGPL-3.0-only WITH openvpn3-openssl-exception
//
 
// A basic reference-counting garbage collection scheme based
// on intrusive pointers, where the reference count is embedded in
// the object via inheritance.  Simply inherit from RC to create an
// object that can be tracked with an RCPtr.
//
// We use tend to use RCPtr (or RCWeakPtr) rather than the other
// smart pointer classes (std or boost) for flexibility and
// performance.
//
// Smart pointers have two basic attributes that determine
// their performance.  Either of these attributes, when required,
// will degrade the performance of the smart pointer:
//
// 1. whether the smart pointer is thread-safe, i.e. it uses an
//    atomic reference counter
// 2. whether the smart pointer can be referrred to via a
//    weak reference
//
// In keeping with the oft-stated C++ motto of only paying for
// what you use, both attributes can be independently controlled.
//
// * thread-unsafe/not-weak-referenceable -- class Foo : public RC<thread_unsafe_refcount>
// * thread-safe/not-weak-referenceable   -- class Foo : public RC<thread_safe_refcount>
// * thread-unsafe/weak-referenceable     -- class Foo : public RCWeak<thread_unsafe_refcount>
// * thread-safe/weak-referenceable       -- class Foo : public RCWeak<thread_safe_refcount>
//
// Thread-safe reference counting can be significantly more expensive
// because an atomic object must be used for the reference count.
// Therefore, thread-safe reference counting should only be used for
// objects that have visibility across multiple threads.
//
// In addition, having an object be weak-referenceable also
// imposes a cost, so it should be avoided unless necessary.
//
// For clarity and as a general convention in the OpenVPN code,
// any object that inherits from RC should also declare a Ptr
// typedef that defines the smart pointer type that should be used to
// track the object, e.g.:
//
// class Foo : public RC<thread_unsafe_refcount> {
// public:
//   typedef RCPtr<Foo> Ptr;        // strong pointer
//   typedef RCWeakPtr<Foo> WPtr;   // weak pointer
// };
//
// This allows a smart-pointer to Foo to be referred to
// as Foo::Ptr or Foo::WPtr.
//
// Note that RC/RCWeak fully supports virtual inheritance.  For
// example, consider the diamond inheritance pattern below, where
// both A and B objects contain their own reference count, but C
// inherits from both A and B.  To prevent C objects from
// having two separate reference counts, it is necessary to
// virtually inherit from RC.
//
// class A : public virtual RC<thread_unsafe_refcount> {}
// class B : public virtual RC<thread_unsafe_refcount> {}
// class C : public A, public B {}
 
#ifndef OPENVPN_COMMON_RC_H
#define OPENVPN_COMMON_RC_H
 
#include <atomic>
#include <utility>
 
#include <openvpn/common/olong.hpp>
 
#ifdef OPENVPN_RC_DEBUG
#include <iostream>
#include <openvpn/common/demangle.hpp>
#endif
 
namespace openvpn {
 
template <typename T>
class RCPtr
{
  public:
    typedef T element_type;
 
    RCPtr() noexcept;
    RCPtr(T *p, const bool add_ref = true) noexcept;
    RCPtr(const RCPtr &rhs) noexcept;
    RCPtr(RCPtr &&rhs) noexcept;
    template <typename U>
    RCPtr(const RCPtr<U> &rhs) noexcept;
    ~RCPtr();
 
    RCPtr &operator=(const RCPtr &rhs) noexcept;
    RCPtr &operator=(RCPtr &&rhs) noexcept;
 
    void reset() noexcept;
    void reset(T *rhs) noexcept;
    void swap(RCPtr &rhs) noexcept;
 
    T *get() const noexcept;
    T &operator*() const noexcept;
    T *operator->() const noexcept;
 
    explicit operator bool() const noexcept;
    bool operator==(const RCPtr &rhs) const;
    bool operator!=(const RCPtr &rhs) const;
 
    RCPtr<T> move_strong() noexcept;
    template <typename U>
    RCPtr<U> static_pointer_cast() const noexcept;
    template <typename U>
    RCPtr<U> dynamic_pointer_cast() const noexcept;
 
  private:
    T *px; 
};
template <typename T>
RCPtr<T>::RCPtr() noexcept
    : px(nullptr){};
template <typename T>
RCPtr<T>::RCPtr(T *p, const bool add_ref) noexcept
    : px(p)
{
    if (px && add_ref)
        intrusive_ptr_add_ref(px);
}
template <typename T>
RCPtr<T>::RCPtr(const RCPtr &rhs) noexcept
    : px(rhs.px)
{
    if (px)
        intrusive_ptr_add_ref(px);
}
template <typename T>
RCPtr<T>::RCPtr(RCPtr &&rhs) noexcept
    : px(rhs.px)
{
    rhs.px = nullptr;
}
template <typename T>
template <typename U>
RCPtr<T>::RCPtr(const RCPtr<U> &rhs) noexcept
    : px(rhs.get())
{
    if (px)
        intrusive_ptr_add_ref(px);
}
template <typename T>
RCPtr<T>::~RCPtr()
{
    if (px)
        intrusive_ptr_release(px);
}
template <typename T>
RCPtr<T> &RCPtr<T>::operator=(const RCPtr &rhs) noexcept
{
    // notice that RCPtr(rhs) is a temp built from rhs, which will decrement old T when scope ends
    RCPtr(rhs).swap(*this);
    return *this;
}
template <typename T>
RCPtr<T> &RCPtr<T>::operator=(RCPtr &&rhs) noexcept
{
    RCPtr(std::move(rhs)).swap(*this);
    return *this;
}
template <typename T>
void RCPtr<T>::reset() noexcept
{
    RCPtr().swap(*this);
}
template <typename T>
void RCPtr<T>::reset(T *rhs) noexcept
{
    RCPtr(rhs).swap(*this);
}
template <typename T>
void RCPtr<T>::swap(RCPtr &rhs) noexcept
{
    std::swap(px, rhs.px);
}
template <typename T>
T *RCPtr<T>::get() const noexcept
{
    return px;
}
template <typename T>
T &RCPtr<T>::operator*() const noexcept
{
    return *px;
}
template <typename T>
T *RCPtr<T>::operator->() const noexcept
{
    return px;
}
template <typename T>
RCPtr<T>::operator bool() const noexcept
{
    return px != nullptr;
}
template <typename T>
bool RCPtr<T>::operator==(const RCPtr &rhs) const
{
    return px == rhs.px;
}
template <typename T>
bool RCPtr<T>::operator!=(const RCPtr &rhs) const
{
    return px != rhs.px;
}
template <typename T>
RCPtr<T> RCPtr<T>::move_strong() noexcept
{
    T *p = px;
    px = nullptr;
    return RCPtr<T>(p, false);
}
template <typename T>
template <typename U>
RCPtr<U> RCPtr<T>::static_pointer_cast() const noexcept
{
    return RCPtr<U>(static_cast<U *>(px));
}
template <typename T>
template <typename U>
RCPtr<U> RCPtr<T>::dynamic_pointer_cast() const noexcept
{
    return RCPtr<U>(dynamic_cast<U *>(px));
}
template <typename T>
class RCWeakPtr
{
    typedef RCPtr<T> Strong;
 
  public:
    typedef T element_type;
 
    RCWeakPtr() noexcept;
    RCWeakPtr(const Strong &p) noexcept;
    RCWeakPtr(T *p) noexcept;
 
    void reset(const Strong &p) noexcept;
    void reset(T *p) noexcept;
    void reset() noexcept;
 
    void swap(RCWeakPtr &other) noexcept;
    olong use_count() const noexcept;
    bool expired() const noexcept;
    Strong lock() const noexcept;
    Strong move_strong() noexcept;
 
  private:
    typename T::Controller::Ptr controller; 
};
template <typename T>
RCWeakPtr<T>::RCWeakPtr() noexcept {};
template <typename T>
RCWeakPtr<T>::RCWeakPtr(const Strong &p) noexcept
{
    if (p)
        controller = p->refcount_.controller;
}
template <typename T>
RCWeakPtr<T>::RCWeakPtr(T *p) noexcept
{
    if (p)
        controller = p->refcount_.controller;
}
template <typename T>
void RCWeakPtr<T>::reset(const Strong &p) noexcept
{
    if (p)
        controller = p->refcount_.controller;
    else
        controller.reset();
}
template <typename T>
void RCWeakPtr<T>::reset(T *p) noexcept
{
    if (p)
        controller = p->refcount_.controller;
    else
        controller.reset();
}
template <typename T>
void RCWeakPtr<T>::reset() noexcept
{
    controller.reset();
}
template <typename T>
void RCWeakPtr<T>::swap(RCWeakPtr &other) noexcept
{
    controller.swap(other.controller);
}
template <typename T>
olong RCWeakPtr<T>::use_count() const noexcept
{
    if (controller)
        return controller->use_count();
    else
        return 0;
}
template <typename T>
bool RCWeakPtr<T>::expired() const noexcept
{
    return use_count() == 0;
}
template <typename T>
typename RCWeakPtr<T>::Strong RCWeakPtr<T>::lock() const noexcept
{
    if (controller)
        return controller->template lock<Strong>();
    else
        return Strong();
}
template <typename T>
typename RCWeakPtr<T>::Strong RCWeakPtr<T>::move_strong() noexcept
{
    typename T::Controller::Ptr c;
    c.swap(controller);
    if (c)
        return c->template lock<Strong>();
    else
        return Strong();
}
 
/* We're pretty sure these are false positives. They only occur with very
   specific compiler versions and/or architectures.
 
   For some reason some gcc versions think that the reference counter goes
   away too soon when destructing certain MultiCompleteType objects. The
   warnings/errors do not tell us why they think that.
 
   So for now we display the warnings, but do not fail -Werror builds over
   them. So that we can fail them for any other new warnings.
 */
#if !defined(__clang__) && defined(__GNUC__)
#pragma GCC diagnostic push
#if __GNUC__ == 12
#pragma GCC diagnostic warning "-Wuse-after-free"
#endif
#if __GNUC__ == 13 || __GNUC__ == 14
#pragma GCC diagnostic warning "-Wstringop-overflow"
#endif
#endif
class thread_unsafe_refcount
{
  public:
    thread_unsafe_refcount() noexcept;
    void operator++() noexcept;
    olong operator--() noexcept;
    bool inc_if_nonzero() noexcept;
    olong use_count() const noexcept;
 
    static constexpr bool is_thread_safe();
 
#ifdef OPENVPN_RC_NOTIFY
    void notify_release() noexcept;
#endif
 
#ifdef OPENVPN_RC_NOTIFY
    template <typename T>
    class ListHead;
#endif
 
  private:
    thread_unsafe_refcount(const thread_unsafe_refcount &) = delete;
    thread_unsafe_refcount &operator=(const thread_unsafe_refcount &) = delete;
 
    olong rc; 
};
inline thread_unsafe_refcount::thread_unsafe_refcount() noexcept
    : rc(olong(0)) {};
inline void thread_unsafe_refcount::operator++() noexcept
{
    ++rc;
}
inline olong thread_unsafe_refcount::operator--() noexcept
{
    return --rc;
}
inline bool thread_unsafe_refcount::inc_if_nonzero() noexcept
{
    if (rc)
    {
        ++rc;
        return true;
    }
    else
        return false;
}
inline olong thread_unsafe_refcount::use_count() const noexcept
{
    return rc;
}
inline constexpr bool thread_unsafe_refcount::is_thread_safe()
{
    return false;
}
 
#ifdef OPENVPN_RC_NOTIFY
inline void thread_unsafe_refcount::notify_release() noexcept
{
}
#endif
 
#ifdef OPENVPN_RC_NOTIFY
template <typename T>
class thread_unsafe_refcount::ListHead
{
  public:
    ListHead() noexcept
        : ptr(nullptr)
    {
    }
 
    T *load() noexcept
    {
        return ptr;
    }
 
    void insert(T *item) noexcept
    {
        item->next = ptr;
        ptr = item;
    }
 
  private:
    ListHead(const ListHead &) = delete;
    ListHead &operator=(const ListHead &) = delete;
 
    T *ptr;
};
#endif
 
class thread_safe_refcount
{
  public:
    thread_safe_refcount() noexcept;
    void operator++() noexcept;
    olong operator--() noexcept;
 
    bool inc_if_nonzero() noexcept;
    olong use_count() const noexcept;
    static constexpr bool is_thread_safe();
 
#ifdef OPENVPN_RC_NOTIFY
    void notify_release() noexcept;
#endif
 
#ifdef OPENVPN_RC_NOTIFY
    template <typename T>
    class ListHead;
#endif
 
  private:
    thread_safe_refcount(const thread_safe_refcount &) = delete;
    thread_safe_refcount &operator=(const thread_safe_refcount &) = delete;
 
    std::atomic<olong> rc;
};
inline thread_safe_refcount::thread_safe_refcount() noexcept
    : rc(olong(0))
{
}
inline void thread_safe_refcount::operator++() noexcept
{
    rc.fetch_add(1, std::memory_order_relaxed);
}
inline olong thread_safe_refcount::operator--() noexcept
{
    // http://www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html
    const olong ret = rc.fetch_sub(1, std::memory_order_release) - 1;
    if (ret == 0)
        std::atomic_thread_fence(std::memory_order_acquire);
    return ret;
}
inline bool thread_safe_refcount::inc_if_nonzero() noexcept
{
    olong previous = rc.load(std::memory_order_relaxed);
    while (true)
    {
        if (!previous)
            break;
        if (rc.compare_exchange_weak(previous, previous + 1, std::memory_order_relaxed))
            break;
    }
    return previous > 0;
}
inline olong thread_safe_refcount::use_count() const noexcept
{
    return rc.load(std::memory_order_relaxed);
}
inline constexpr bool thread_safe_refcount::is_thread_safe()
{
    return true;
}
 
#ifdef OPENVPN_RC_NOTIFY
inline void thread_safe_refcount::notify_release() noexcept
{
}
#endif
 
#ifdef OPENVPN_RC_NOTIFY
template <typename T>
class thread_safe_refcount::ListHead
{
  public:
    ListHead() noexcept
        : ptr(nullptr)
    {
    }
 
    T *load() noexcept
    {
        return ptr;
    }
 
    void insert(T *item) noexcept
    {
        item->next = ptr;
        ptr = item;
    }
 
  private:
    ListHead(const ListHead &) = delete;
    ListHead &operator=(const ListHead &) = delete;
 
    T *ptr;
};
#endif
 
 
#if !defined(__clang__) && defined(__GNUC__)
#pragma GCC diagnostic pop
#endif
 
template <typename RCImpl>
class RC
{
  public:
    typedef RCPtr<RC> Ptr;
 
    RC() noexcept = default;
    virtual ~RC() = default;
    RC(const RC &) = delete;
    RC &operator=(const RC &) = delete;
 
    olong use_count() const noexcept;
    static constexpr bool is_thread_safe();
 
  private:
    template <typename R>
    friend void intrusive_ptr_add_ref(R *rcptr) noexcept;
    template <typename R>
    friend void intrusive_ptr_release(R *rcptr) noexcept;
    RCImpl refcount_;
};
template <typename RCImpl>
olong RC<RCImpl>::use_count() const noexcept
{
    return refcount_.use_count();
}
template <typename RCImpl>
constexpr bool RC<RCImpl>::is_thread_safe()
{
    return RCImpl::is_thread_safe();
}
 
template <typename RCImpl>
class RCCopyable
{
  public:
    virtual ~RCCopyable() = default;
    RCCopyable() noexcept = default;
    RCCopyable(const RCCopyable &) noexcept;
    RCCopyable(RCCopyable &&) noexcept;
    RCCopyable &operator=(const RCCopyable &) noexcept;
    RCCopyable &operator=(RCCopyable &&) noexcept;
    olong use_count() const noexcept;
 
  private:
    template <typename R>
    friend void intrusive_ptr_add_ref(R *rcptr) noexcept;
    template <typename R>
    friend void intrusive_ptr_release(R *rcptr) noexcept;
    RCImpl refcount_;
};
 
template <typename RCImpl>
RCCopyable<RCImpl>::RCCopyable(const RCCopyable &) noexcept {};
template <typename RCImpl>
RCCopyable<RCImpl>::RCCopyable(RCCopyable &&) noexcept {};
template <typename RCImpl>
RCCopyable<RCImpl> &RCCopyable<RCImpl>::operator=(const RCCopyable &) noexcept
{
    return *this;
}
template <typename RCImpl>
RCCopyable<RCImpl> &RCCopyable<RCImpl>::operator=(RCCopyable &&) noexcept
{
    return *this;
}
template <typename RCImpl>
olong RCCopyable<RCImpl>::use_count() const noexcept
{
    return refcount_.use_count();
}
 
template <typename RCImpl> // RCImpl = thread_safe_refcount or thread_unsafe_refcount
class RCWeak
{
    template <typename T>
    friend class RCWeakPtr;
 
#ifdef OPENVPN_RC_NOTIFY
    // Base class of release notification callables
    class NotifyBase;
    // A release notification callable
    template <typename CALLABLE>
    class NotifyItem;
    // Head of a linked-list of release notification callables
    class NotifyListHead;
#endif
 
    struct Controller;
    struct ControllerRef;
 
  public:
    typedef RCPtr<RCWeak> Ptr;
    typedef RCWeakPtr<RCWeak> WPtr;
 
    RCWeak() noexcept
        : refcount_(this) {};
 
    virtual ~RCWeak() = default;
    RCWeak(const RCWeak &) = delete;
    RCWeak &operator=(const RCWeak &) = delete;
 
#ifdef OPENVPN_RC_NOTIFY
    // Add observers to be called just prior to object deletion,
    // but after refcount has been decremented to 0.  At this
    // point, all weak pointers have expired, and no strong
    // pointers are outstanding.  Callables can access the
    // object by raw pointer but must NOT attempt to create a
    // strong pointer referencing the object.
 
    template <typename CALLABLE>
    void rc_release_notify(const CALLABLE &c) noexcept
    {
        refcount_.notify.add(c);
    }
 
    template <typename CALLABLE>
    void rc_release_notify(CALLABLE &&c) noexcept
    {
        refcount_.notify.add(std::move(c));
    }
#endif
 
  private:
    template <typename R>
    friend void intrusive_ptr_add_ref(R *rcptr) noexcept;
    template <typename R>
    friend void intrusive_ptr_release(R *rcptr) noexcept;
 
    ControllerRef refcount_; 
};
 
template <typename RCImpl>
struct RCWeak<RCImpl>::Controller : public RC<RCImpl>
{
    typedef RCPtr<Controller> Ptr;
 
    Controller(RCWeak *parent_arg) noexcept;
 
    olong use_count() const noexcept;
 
    template <typename PTR>
    PTR lock() noexcept;
 
    RCWeak *const parent; 
    RCImpl rc;            
};
template <typename RCImpl>
RCWeak<RCImpl>::Controller::Controller(RCWeak *parent_arg) noexcept
    : parent(parent_arg){};
template <typename RCImpl>
olong RCWeak<RCImpl>::Controller::use_count() const noexcept
{
    return rc.use_count();
}
template <typename RCImpl>
template <typename PTR>
PTR RCWeak<RCImpl>::Controller::lock() noexcept
{
    if (rc.inc_if_nonzero())
        return PTR(static_cast<typename PTR::element_type *>(parent), false);
    else
        return PTR();
}
 
template <typename RCImpl>
struct RCWeak<RCImpl>::ControllerRef
{
    explicit ControllerRef(RCWeak *parent) noexcept;
 
    void operator++() noexcept;
    olong operator--() noexcept;
 
#ifdef OPENVPN_RC_NOTIFY
    void notify_release() noexcept;
#endif
 
    typename Controller::Ptr controller; 
 
#ifdef OPENVPN_RC_NOTIFY
    NotifyListHead notify; // linked list of callables to be notified on object release
#endif
};
template <typename RCImpl>
RCWeak<RCImpl>::ControllerRef::ControllerRef(RCWeak *parent) noexcept
    : controller(new Controller(parent)){};
template <typename RCImpl>
void RCWeak<RCImpl>::ControllerRef::operator++() noexcept
{
    ++controller->rc;
}
template <typename RCImpl>
olong RCWeak<RCImpl>::ControllerRef::operator--() noexcept
{
    return --controller->rc;
}
 
#ifdef OPENVPN_RC_NOTIFY
template <typename RCImpl>
void RCWeak<RCImpl>::ControllerRef::notify_release() noexcept
{
    notify.release();
}
#endif
 
#ifdef OPENVPN_RC_NOTIFY
// Base class of release notification callables
template <typename RCImpl>
class RCWeak<RCImpl>::NotifyBase
{
  public:
    NotifyBase() noexcept = default;
    virtual void call() noexcept = 0;
    virtual ~NotifyBase() = default;
    NotifyBase *next = nullptr;
 
  private:
    NotifyBase(const NotifyBase &) = delete;
    NotifyBase &operator=(const NotifyBase &) = delete;
};
 
// A release notification callable
template <typename RCImpl>
template <typename CALLABLE>
class RCWeak<RCImpl>::NotifyItem : public NotifyBase
{
  public:
    NotifyItem(const CALLABLE &c) noexcept
        : callable(c)
    {
    }
 
    NotifyItem(CALLABLE &&c) noexcept
        : callable(std::move(c))
    {
    }
 
  private:
    void call() noexcept override
    {
        callable();
    }
 
    CALLABLE callable;
};
 
// Head of a linked-list of release notification callables
template <typename RCImpl>
class RCWeak<RCImpl>::NotifyListHead
{
  public:
    NotifyListHead() noexcept
    {
    }
 
    template <typename CALLABLE>
    void add(const CALLABLE &c) noexcept
    {
        NotifyBase *item = new NotifyItem<CALLABLE>(c);
        head.insert(item);
    }
 
    template <typename CALLABLE>
    void add(CALLABLE &&c) noexcept
    {
        NotifyBase *item = new NotifyItem<CALLABLE>(std::move(c));
        head.insert(item);
    }
 
    void release() noexcept
    {
        // In thread-safe mode, list traversal is guaranteed to be
        // contention-free because we are not called until refcount
        // reaches zero and after a std::memory_order_acquire fence.
        NotifyBase *nb = head.load();
        while (nb)
        {
            NotifyBase *next = nb->next;
            nb->call();
            delete nb;
            nb = next;
        }
    }
 
  private:
    NotifyListHead(const NotifyListHead &) = delete;
    NotifyListHead &operator=(const NotifyListHead &) = delete;
 
    typename RCImpl::template ListHead<NotifyBase> head;
};
#endif
template <typename R>
inline void intrusive_ptr_add_ref(R *rcptr) noexcept
{
#ifdef OPENVPN_RC_DEBUG
    std::cout << "ADD REF " << cxx_demangle(typeid(rcptr).name()) << std::endl;
#endif
    ++rcptr->refcount_;
}
template <typename R>
inline void intrusive_ptr_release(R *rcptr) noexcept
{
    if (--rcptr->refcount_ == 0)
    {
#ifdef OPENVPN_RC_DEBUG
        std::cout << "DEL OBJ " << cxx_demangle(typeid(rcptr).name()) << std::endl;
#endif
#ifdef OPENVPN_RC_NOTIFY
        rcptr->refcount_.notify_release();
#endif
        delete rcptr;
    }
    else
    {
#ifdef OPENVPN_RC_DEBUG
        std::cout << "REL REF " << cxx_demangle(typeid(rcptr).name()) << std::endl;
#endif
    }
}
 
} // namespace openvpn
 
#endif // OPENVPN_COMMON_RC_H