UT_IntrusivePtr.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_IntrusivePtr.h (UT Library, C++)
 *
 * COMMENTS:    A wrapper around hboost::intrusive_ptr.
 *
 */

#ifndef __UT_INTRUSIVEPTR_H_INCLUDED__
#define __UT_INTRUSIVEPTR_H_INCLUDED__

#include <SYS/SYS_AtomicInt.h>
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_PointerHash.h>
#include <SYS/SYS_Types.h>
#include <hboost/smart_ptr/intrusive_ptr.hpp>   // IWYU pragma: export

#include <memory>                   // for std::default_delete

/// @brief Wrapper around hboost::intrusive_ptr
///
/// An intrusive pointer assumes that the referenced object implements
/// reference counting on itself.  The reference counting is implemented using
/// the methods @c intrusive_ptr_add_ref() and @c intrusive_ptr_release().
///
/// For simple usages, simply derive from UT_IntrusiveRefCounter.
///
/// Here's a roll your own example: @code
///     class Foo
///     {
///     public:
///         Foo() : myCount(0) {}
///        ~Foo() {}
///         void        incref()
///                     {
///                         myCount.add(1);
///                     }
///         void        decref()
///                     {
///                         if (myCount.add(-1) == 0)
///                             delete this;
///                     }
///         SYS_AtomicInt32     myCount;
///     };
///     static inline void intrusive_ptr_add_ref(Foo *o) { o->incref(); }
///     static inline void intrusive_ptr_release(Foo *o) { o->decref(); }
///
///     using FooHandle = UT_IntrusivePtr<Foo>;
/// @endcode
/// @see UT_SharedPtr
template<class T>
class UT_IntrusivePtr : public hboost::intrusive_ptr<T>
{
public:
    SYS_FORCE_INLINE
    UT_IntrusivePtr() noexcept
        : hboost::intrusive_ptr<T>() {}

    // NOTE: This should really be explicit, but there are so many
    // places currently implicitly casting to UT_IntrusivePtr that
    // it could take quite a while to fix.
    SYS_FORCE_INLINE
    /*explicit*/ UT_IntrusivePtr(T *p)
        : hboost::intrusive_ptr<T>(p, true) {}

    SYS_FORCE_INLINE
    UT_IntrusivePtr(T *p, bool add_ref)
        : hboost::intrusive_ptr<T>(p, add_ref) {}

    SYS_FORCE_INLINE
    UT_IntrusivePtr(const UT_IntrusivePtr<T> &p)
        : hboost::intrusive_ptr<T>(p) {}

    template <typename Y>
    SYS_FORCE_INLINE
    UT_IntrusivePtr(const UT_IntrusivePtr<Y> &p)
        : hboost::intrusive_ptr<T>(p) {}

    SYS_FORCE_INLINE
    UT_IntrusivePtr(UT_IntrusivePtr<T> &&p)
        : hboost::intrusive_ptr<T>(std::move(p)) {}

    template <typename Y>
    SYS_FORCE_INLINE
    UT_IntrusivePtr(UT_IntrusivePtr<Y> &&p)
        : hboost::intrusive_ptr<T>(std::move(p)) {}

    SYS_FORCE_INLINE
    UT_IntrusivePtr<T> &operator=(const UT_IntrusivePtr<T> &that)
    {
        hboost::intrusive_ptr<T>::operator=(that);
        return *this;
    }

    template <typename Y>
    SYS_FORCE_INLINE
    UT_IntrusivePtr<T> &operator=(const UT_IntrusivePtr<Y> &that)
    {
        hboost::intrusive_ptr<T>::operator=(that);
        return *this;
    }

    SYS_FORCE_INLINE
    UT_IntrusivePtr<T> &operator=(UT_IntrusivePtr<T> &&that)
    {
        hboost::intrusive_ptr<T>::operator=(std::move(that));
        return *this;
    }

    template <typename Y>
    SYS_FORCE_INLINE
    UT_IntrusivePtr<T> &operator=(UT_IntrusivePtr<Y> &&that)
    {
        hboost::intrusive_ptr<T>::operator=(std::move(that));
        return *this;
    }
};

/// std::hash specialization for UT_IntrusivePtr<T>
namespace std
{
    template <typename T>
    struct hash<UT_IntrusivePtr<T>>
    {
        size_t operator()(const UT_IntrusivePtr<T> &p) const
        {
            return SYSpointerHash(p.get());
        }
    };
}

/// Constructs an object of type T wrapped in a UT_IntrusivePtr
template <typename T, typename... ArgsT>
UT_IntrusivePtr<T>
UTmakeIntrusive(ArgsT &&... args)
{
    return UT_IntrusivePtr<T>(new T(std::forward<ArgsT>(args)...));
}

/// Thread-safe policy for UT_IntrusiveRefCounter
struct UT_IntrusiveThreadSafeCounterPolicy
{
    using type = SYS_AtomicInt32;
    using pod_type = uint32;

    SYS_FORCE_INLINE
    static uint32 load(const type& counter) noexcept
    {
        return counter.relaxedLoad();
    }

    SYS_FORCE_INLINE
    static void increment(type& counter) noexcept
    {
        (void)counter.add(1);
    }
    SYS_FORCE_INLINE
    static void increment(type& counter, pod_type refs_to_add) noexcept
    {
        (void)counter.add(refs_to_add);
    }

    SYS_FORCE_INLINE
    static uint32 decrement(type& counter) noexcept
    {
        return counter.add(-1);
    }
    SYS_FORCE_INLINE
    static uint32 decrement(type& counter, pod_type refs_to_remove) noexcept
    {
        return counter.add(-int32(refs_to_remove));
    }

    SYS_FORCE_INLINE
    static bool conditionalIncrement(type& counter) noexcept
    {
        // This is the same idea as weak_ptr::lock(), where we only want to
        // increment the reference count if it's non-zero.
        // See <boost/smart_ptr/detail/sp_counted_base_std_atomic.hpp>
        //
        // Note that relaxed operations are acceptable here:
        // https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering notes:
        //   - Typical use for relaxed memory ordering is incrementing
        //     counters, such as the reference counters of std::shared_ptr,
        //     since this only requires atomicity, but not ordering or
        //     synchronization (note that decrementing the shared_ptr counters
        //     requires acquire-release synchronization with the destructor)

        int32 r = counter.relaxedLoad();

        while (true)
        {
            if (r == 0)
                return r;

            if (counter.compareExchangeWeak(
                        r, r + 1,
                        SYS_MEMORY_ORDER_RELAXED,
                        SYS_MEMORY_ORDER_RELAXED))
            {
                return r;
            }
        }
    }
};

/// NON Thread-safe policy for UT_IntrusiveRefCounter
struct UT_IntrusiveNonThreadSafeCounterPolicy
{
    using type = uint32;
    using pod_type = uint32;

    SYS_FORCE_INLINE
    static uint32 load(const type& counter) noexcept { return counter; }

    SYS_FORCE_INLINE
    static void increment(type& counter) noexcept
    {
        ++counter;
    }
    SYS_FORCE_INLINE
    static void increment(type& counter, pod_type refs_to_add) noexcept
    {
        counter += refs_to_add;
    }

    SYS_FORCE_INLINE
    static uint32 decrement(type& counter) noexcept
    {
        return (--counter);
    }
    SYS_FORCE_INLINE
    static uint32 decrement(type& counter, pod_type refs_to_remove) noexcept
    {
        return (counter -= refs_to_remove);
    }

    SYS_FORCE_INLINE
    static bool conditionalIncrement(type& counter) noexcept
    {
        pod_type r = counter;
        if (r != 0)
            ++counter;

        return r != 0;
    }
};

// Forward declarations for friends.
template <
    typename DerivedT,
    typename Deleter = std::default_delete<DerivedT>,
    typename CounterPolicyT = UT_IntrusiveThreadSafeCounterPolicy
>
class UT_IntrusiveRefCounter; 

template <typename DerivedT, typename Deleter, typename CounterPolicyT>
void intrusive_ptr_add_ref(
    const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p) noexcept;

template <typename DerivedT, typename Deleter, typename CounterPolicyT>
void intrusive_ptr_release(
    const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p) noexcept;

template <typename DerivedT, typename Deleter, typename CounterPolicyT>
void intrusive_ptr_add_ref(
    const UT_IntrusiveRefCounter<DerivedT, Deleter, CounterPolicyT>* p,
    typename CounterPolicyT::pod_type refs_to_add) noexcept;

template <typename DerivedT, typename Deleter, typename CounterPolicyT>
void intrusive_ptr_release(
    const UT_IntrusiveRefCounter<DerivedT, Deleter, CounterPolicyT>* p,
    typename CounterPolicyT::pod_type refs_to_remove) noexcept;

/// @brief A reference counter base class for use with UT_IntrusivePtr
///
/// This base class can be used with user-defined classes to add support for
/// @c UT_IntrusivePtr. The class contains a reference counter defined by the
/// @c CounterPolicyT.  Upon releasing the last @c UT_IntrusivePtr referencing
/// the object derived from the @c UT_IntrusiveRefCounter class, operator
/// @c delete is automatically called on the pointer to the object.
/// 
/// The other template parameter, @c DerivedT, is the user's class that
/// derives from @c UT_IntrusiveRefCounter.
///
/// Example: @code
///     class MyClass : public UT_IntrusiveRefCounter<MyClass>
///         { ... };
///     using MyClassPtr = UT_IntrusivePtr<MyClass>;
/// @endcode
template <
    typename DerivedT,
    typename Deleter,
    typename CounterPolicyT
>
class UT_IntrusiveRefCounter
{
public:
    /// Default constructor: Sets counter to 0.
    SYS_FORCE_INLINE
    UT_IntrusiveRefCounter() noexcept
        : myRefCount(0)
    {
    }
    /// Copy constructor: Sets counter to 0.
    SYS_FORCE_INLINE
    UT_IntrusiveRefCounter(const UT_IntrusiveRefCounter&) noexcept
        : myRefCount(0)
    {
    }
    /// Assignment operator: Does not modify counter.
    UT_IntrusiveRefCounter& operator=(const UT_IntrusiveRefCounter&) noexcept
    {
        return *this;
    }
    /// Return current counter
    SYS_FORCE_INLINE
    uint32 use_count() const noexcept
    {
        return CounterPolicyT::load(myRefCount);
    }

    /// Adds a reference only if the reference count is not zero.
    /// This can be used to implement an operation similar to weak_ptr::lock().
    SYS_FORCE_INLINE
    bool conditionalAddRef() noexcept
    {
        return CounterPolicyT::conditionalIncrement(myRefCount);
    }

protected:
    /// Destructor: Only derived classes can destruct this.
    SYS_FORCE_INLINE
    ~UT_IntrusiveRefCounter()
    {
    }

private:
    mutable typename CounterPolicyT::type    myRefCount;

    friend void intrusive_ptr_add_ref<DerivedT,Deleter,CounterPolicyT>(
        const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p
        ) noexcept;
    friend void intrusive_ptr_release<DerivedT,Deleter,CounterPolicyT>(
        const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p
        ) noexcept;
    friend void intrusive_ptr_add_ref<DerivedT,Deleter,CounterPolicyT>(
        const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p,
        typename CounterPolicyT::pod_type refs_to_add) noexcept;
    friend void intrusive_ptr_release<DerivedT,Deleter,CounterPolicyT>(
        const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p,
        typename CounterPolicyT::pod_type refs_to_remove) noexcept;

};

template <typename DerivedT, typename Deleter, typename CounterPolicyT>
SYS_FORCE_INLINE void
intrusive_ptr_add_ref(
    const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p) noexcept
{
    CounterPolicyT::increment(p->myRefCount);
}
template <typename DerivedT, typename Deleter, typename CounterPolicyT>
SYS_FORCE_INLINE void
intrusive_ptr_release(
    const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p) noexcept
{
    if (CounterPolicyT::decrement(p->myRefCount) == 0)
    {
        Deleter d;
        d(SYSconst_cast(static_cast<const DerivedT *>(p)));
    }
}

template <typename DerivedT, typename Deleter, typename CounterPolicyT>
SYS_FORCE_INLINE void
intrusive_ptr_add_ref(
    const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p,
    typename CounterPolicyT::pod_type refs_to_add) noexcept
{
    CounterPolicyT::increment(p->myRefCount, refs_to_add);
}
template <typename DerivedT, typename Deleter, typename CounterPolicyT>
SYS_FORCE_INLINE void
intrusive_ptr_release(
    const UT_IntrusiveRefCounter<DerivedT,Deleter,CounterPolicyT>* p,
    typename CounterPolicyT::pod_type refs_to_remove) noexcept
{
    if (CounterPolicyT::decrement(p->myRefCount, refs_to_remove) == 0)
    {
        Deleter d;
        d(SYSconst_cast(static_cast<const DerivedT *>(p)));
    }
}

// For UT::ArraySet.
namespace UT
{
template <typename T>
struct DefaultClearer;

template <typename T>
struct DefaultClearer<UT_IntrusivePtr<T>>
{
    static void clear(UT_IntrusivePtr<T> &v)
                    { v = UT_IntrusivePtr<T>(); }
    static bool isClear(const UT_IntrusivePtr<T> &v)
                    { return v.get() == nullptr; }
    static void clearConstruct(UT_IntrusivePtr<T> *p)
                    { new ((void *)p) UT_IntrusivePtr<T>(nullptr); }
    static const bool clearNeedsDestruction = false;
};
} // namespace UT

#endif // __UT_INTRUSIVEPTR_H_INCLUDED__