openvpn3/openvpn/common/rc.hpp

//    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-2015 OpenVPN Technologies, Inc.
//
//    This program is free software: you can redistribute it and/or modify
//    it under the terms of the GNU Affero General Public License Version 3
//    as published by the Free Software Foundation.
//
//    This program is distributed in the hope that it will be useful,
//    but WITHOUT ANY WARRANTY; without even the implied warranty of
//    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
//    GNU Affero General Public License for more details.
//
//    You should have received a copy of the GNU Affero General Public License
//    along with this program in the COPYING file.
//    If not, see <http://www.gnu.org/licenses/>.

// A basic reference-counting garbage collection scheme based on
// boost::intrusive_ptr.  Simply inherit from RC to create an
// object that can be tracked with an intrusive_ptr.
//
// We use tend to use boost::intrusive_ptr rather than the other boost
// smart pointer classes because it is more efficient to have the reference
// count itself baked into the object being tracked.  The downside
// of boost::intrusive_ptr is that it cannot be used for weak references.
// Another downside of reference counting in general is that it doesn't handle
// cycles, so be sure to manually break any cycles that might arise
// before the object chain is considered for garbage collection.
//
// When using the RC template class, it is necessary to specify whether
// the reference count should be thread safe or unsafe, i.e.:
//
// class Foo : public RC<thread_safe_refcount> {}
//   or
// class Bar : public RC<thread_unsafe_refcount> {}
//
// Thread-safe reference counting can be significantly more expensive
// on SMP machines because the bus must be locked before the reference
// count can be incremented/decremented.  Therefore thread-safe reference
// counting should only be used for objects that have visibility across
// multiple threads.
//
// For clarity, 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 boost::intrusive_ptr<Foo> Ptr;
// };
//
// This allows a smart-pointer to Foo to be referred to
// as Foo::Ptr

#ifndef OPENVPN_COMMON_RC_H
#define OPENVPN_COMMON_RC_H

#include <atomic>

#include <boost/intrusive_ptr.hpp>

#include <openvpn/common/olong.hpp>

namespace openvpn {

  typedef olong thread_unsafe_refcount;

  class thread_safe_refcount
  {
  public:
    thread_safe_refcount(const olong value)
      : rc(value)
    {
    }

    void operator++()
    {
      rc.fetch_add(1, std::memory_order_relaxed);
    }

    olong operator--()
    {
      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;
    }

  private:
    std::atomic<olong> rc;
  };

  // Reference count base class for objects tracked by boost::intrusive_ptr.
  // Disallows copying and assignment.
  template <typename RCImpl> // RCImpl = thread_safe_refcount or thread_unsafe_refcount
  class RC
  {
    RC(const RC&) = delete;
    RC& operator=(const RC&) = delete;

  public:
    RC() noexcept : refcount_(0) {}
    virtual ~RC() {}
  private:
    template <typename R> friend void intrusive_ptr_add_ref(R* p) noexcept;
    template <typename R> friend void intrusive_ptr_release(R* p) noexcept;
    RCImpl refcount_;
  };

  // Like RC, but allows object to be copied and assigned.
  template <typename RCImpl> // RCImpl = thread_safe_refcount or thread_unsafe_refcount
  class RCCopyable
  {
  public:
    RCCopyable() noexcept : refcount_(0) {}
    RCCopyable(const RCCopyable&) noexcept : refcount_(0) {}
    RCCopyable& operator=(const RCCopyable&) noexcept { return *this; }
    virtual ~RCCopyable() {}
  private:
    template <typename R> friend void intrusive_ptr_add_ref(R* p) noexcept;
    template <typename R> friend void intrusive_ptr_release(R* p) noexcept;
    RCImpl refcount_;
  };

#if !defined(OPENVPN_RC_USERDEF)

  template <typename R>
  inline void intrusive_ptr_add_ref(R *p) noexcept
  {
    ++p->refcount_;
  }

  template <typename R>
  inline void intrusive_ptr_release(R *p) noexcept
  {
    if (--p->refcount_ == 0)
      delete p;
  }

#endif

} // namespace openvpn

#endif // OPENVPN_COMMON_RC_H