refPtr.h

Go to the documentation of this file.

//
// Copyright 2016 Pixar
//
// Licensed under the Apache License, Version 2.0 (the "Apache License")
// with the following modification; you may not use this file except in
// compliance with the Apache License and the following modification to it:
// Section 6. Trademarks. is deleted and replaced with:
//
// 6. Trademarks. This License does not grant permission to use the trade
//    names, trademarks, service marks, or product names of the Licensor
//    and its affiliates, except as required to comply with Section 4(c) of
//    the License and to reproduce the content of the NOTICE file.
//
// You may obtain a copy of the Apache License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the Apache License with the above modification is
// distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied. See the Apache License for the specific
// language governing permissions and limitations under the Apache License.
//
#ifndef PXR_BASE_TF_REF_PTR_H
#define PXR_BASE_TF_REF_PTR_H


#include "pxr/pxr.h"

#include "pxr/base/tf/diagnosticLite.h"
#include "pxr/base/tf/nullPtr.h"
#include "pxr/base/tf/refBase.h"
#include "pxr/base/tf/safeTypeCompare.h"
#include "pxr/base/tf/typeFunctions.h"
#include "pxr/base/tf/api.h"

#include "pxr/base/arch/hints.h"

#include <boost/functional/hash_fwd.hpp>

#include <typeinfo>
#include <type_traits>
#include <cstddef>

PXR_NAMESPACE_OPEN_SCOPE

// Tf_SupportsUniqueChanged is a metafunction that may be specialized to return
// false for classes (and all derived classes) that *cannot* ever invoke unique
// changed listeners.
template <class T>
struct Tf_SupportsUniqueChanged {
    static const bool Value = true;
};

// Remnants are never able to support weak changed listeners.
class Tf_Remnant;
template <>
struct Tf_SupportsUniqueChanged<Tf_Remnant> {
    static const bool Value = false;
};

class TfWeakBase;

template <class T> class TfWeakPtr;
template <template <class> class X, class Y>
class TfWeakPtrFacade;

// Functions used for tracking.  Do not implement these.
inline void Tf_RefPtrTracker_FirstRef(const void*, const void*) { }
inline void Tf_RefPtrTracker_LastRef(const void*, const void*) { }
inline void Tf_RefPtrTracker_New(const void*, const void*) { }
inline void Tf_RefPtrTracker_Delete(const void*, const void*) { }
inline void Tf_RefPtrTracker_Assign(const void*, const void*, const void*) { }

// This code is used to increment and decrement ref counts in the common case.
// It may lock and invoke the unique changed listener, if the reference count
// becomes unique or non-unique.
struct Tf_RefPtr_UniqueChangedCounter {
    static inline int
    AddRef(TfRefBase const *refBase)
    {
        if (refBase) {
            // Check to see if we need to invoke the unique changed listener.
            if (refBase->_shouldInvokeUniqueChangedListener)
                return _AddRef(refBase);
            else
                return refBase->GetRefCount()._FetchAndAdd(1);
        }
        return 0;
    }

    static inline bool
    RemoveRef(TfRefBase const* refBase) {
        if (refBase) {
            // Check to see if we need to invoke the unique changed listener.
            return refBase->_shouldInvokeUniqueChangedListener ?
                        _RemoveRef(refBase) :
                        refBase->GetRefCount()._DecrementAndTestIfZero();
        }
        return false;
    }

    // Increment ptr's count if it is not zero.  Return true if done so
    // successfully, false if its count is zero.
    static inline bool
    AddRefIfNonzero(TfRefBase const *ptr) {
        if (!ptr)
            return false;
        if (ptr->_shouldInvokeUniqueChangedListener) {
            return _AddRefIfNonzero(ptr);
        } else {
            auto &counter = ptr->GetRefCount()._counter;
            auto val = counter.load();
            do {
                if (val == 0)
                    return false;
            } while (!counter.compare_exchange_weak(val, val + 1));
            return true;
        }
    }
    
    TF_API static bool _RemoveRef(TfRefBase const *refBase);

    TF_API static int _AddRef(TfRefBase const *refBase);

    TF_API static bool _AddRefIfNonzero(TfRefBase const *refBase);
};

// This code is used to increment and decrement ref counts in the case where
// the object pointed to explicitly does not support unique changed listeners.
struct Tf_RefPtr_Counter {
    static inline int
    AddRef(TfRefBase const *refBase) {
        if (refBase)
            return refBase->GetRefCount()._FetchAndAdd(1);
        return 0;
    }

    static inline bool
    RemoveRef(TfRefBase const *ptr) {
        return (ptr && (ptr->GetRefCount()._DecrementAndTestIfZero()));
    }

    // Increment ptr's count if it is not zero.  Return true if done so
    // successfully, false if its count is zero.
    static inline bool
    AddRefIfNonzero(TfRefBase const *ptr) {
        if (!ptr)
            return false;
        auto &counter = ptr->GetRefCount()._counter;
        auto val = counter.load();
        do {
            if (val == 0)
                return false;
        } while (!counter.compare_exchange_weak(val, val + 1));
        return true;
    }
};

// Helper to post a fatal error when a NULL Tf pointer is dereferenced.
[[noreturn]]
TF_API void
Tf_PostNullSmartPtrDereferenceFatalError(const TfCallContext &, const char *);

template <class T>
class TfRefPtr {
    // Select the counter based on whether T supports unique changed listeners.
    using _Counter = typename std::conditional<
        Tf_SupportsUniqueChanged<T>::Value &&
        !std::is_convertible<T*, TfSimpleRefBase*>::value,
        Tf_RefPtr_UniqueChangedCounter,
        Tf_RefPtr_Counter>::type;
    
public:
    typedef T DataType;


    template <class U> struct Rebind {
        typedef TfRefPtr<U> Type;
    };    

    TfRefPtr() : _refBase(nullptr) {
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
    }

    TfRefPtr(TfRefPtr<T>&& p) : _refBase(p._refBase) {
        p._refBase = nullptr;
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
        Tf_RefPtrTracker_Assign(&p, p._GetObjectForTracking(),
                                _GetObjectForTracking());
    }

    TfRefPtr(const TfRefPtr<T>& p) : _refBase(p._refBase) {
        _AddRef();
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
    }

    template <template <class> class X, class U>
    inline TfRefPtr(const TfWeakPtrFacade<X, U>& p,
                    typename std::enable_if<
                        std::is_convertible<U*, T*>::value
                    >::type * = 0);

#if defined(doxygen)
    friend inline TfRefPtr TfCreateRefPtr(T*);
#else
    template <class U>
    friend inline TfRefPtr<U> TfCreateRefPtr(U*);
#endif

    template <class U>
    explicit TfRefPtr(
        U* ptr, typename std::enable_if<
            std::is_convertible<U*, T*>::value>::type * = nullptr) :
        _refBase(ptr)
    {
        _AddRef();
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
    }

    TfRefPtr(TfNullPtrType) : _refBase(nullptr)
    {
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
    }

    TfRefPtr(std::nullptr_t) : _refBase(nullptr)
    {
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
    }

    TfRefPtr<T>& operator=(const TfRefPtr<T>& p) {
        //
        // It is quite possible for
        //   ptr = TfNullPtr;
        // to delete the space that ptr actually lives in (this happens
        // when you use a circular reference to keep an object alive).
        // To avoid a crash, we have to ensure that deletion of the object
        // is the last thing done in the assignment; so we use some
        // local variables to help us out.
        //

        Tf_RefPtrTracker_Assign(this, p._GetObjectForTracking(),
                                _GetObjectForTracking());

        const TfRefBase* tmp = _refBase;
        _refBase = p._refBase;

        p._AddRef();            // first!
        _RemoveRef(tmp);        // second!
        return *this;
    }

    TfRefPtr<T>& operator=(TfRefPtr<T>&& p) {
        // See comment in assignment operator.
        Tf_RefPtrTracker_Assign(this, p._GetObjectForTracking(),
                                _GetObjectForTracking());
        Tf_RefPtrTracker_Assign(&p, nullptr,
                                p._GetObjectForTracking());

        const TfRefBase* tmp = _refBase;
        _refBase = p._refBase;
        p._refBase = nullptr;
        
        _RemoveRef(tmp);
        return *this;
    }

    ~TfRefPtr() {
        Tf_RefPtrTracker_Delete(this, _GetObjectForTracking());
        _RemoveRef(_refBase);
    }

#if !defined(doxygen)
    template <class U>
#endif
    TfRefPtr(const TfRefPtr<U>& p) : _refBase(p._refBase) {
        static_assert(std::is_convertible<U*, T*>::value, "");
        _AddRef();
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
    }

#if !defined(doxygen)
    template <class U>
#endif
    TfRefPtr(TfRefPtr<U>&& p) : _refBase(p._refBase) {
        static_assert(std::is_convertible<U*, T*>::value, "");
        p._refBase = nullptr;
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
        Tf_RefPtrTracker_Assign(&p, p._GetObjectForTracking(),
                                _GetObjectForTracking());
    }

#if !defined(doxygen)
    template <class U>
#endif
    TfRefPtr<T>& operator=(const TfRefPtr<U>& p) {
        static_assert(std::is_convertible<U*, T*>::value, "");

        Tf_RefPtrTracker_Assign(this,
                                reinterpret_cast<T*>(p._GetObjectForTracking()),
                                _GetObjectForTracking());
        const TfRefBase* tmp = _refBase;
        _refBase = p._GetData();
        p._AddRef();            // first!
        _RemoveRef(tmp);        // second!
        return *this;
    }

#if !defined(doxygen)
    template <class U>
#endif
    TfRefPtr<T>& operator=(TfRefPtr<U>&& p) {
        static_assert(std::is_convertible<U*, T*>::value, "");

        Tf_RefPtrTracker_Assign(this,
                                reinterpret_cast<T*>(p._GetObjectForTracking()),
                                _GetObjectForTracking());
        Tf_RefPtrTracker_Assign(&p,
                                nullptr,
                                reinterpret_cast<T*>(p._GetObjectForTracking()));
        const TfRefBase* tmp = _refBase;
        _refBase = p._GetData();
        p._refBase = nullptr;
        _RemoveRef(tmp);
        return *this;
    }

#if !defined(doxygen)
    template <class U>
#endif
    auto operator==(const TfRefPtr<U>& p) const 
        -> decltype(std::declval<T *>() == std::declval<U *>(), bool()) {
        return _refBase == p._refBase;
    }

#if !defined(doxygen)
    template <class U>
#endif
    auto operator!=(const TfRefPtr<U>& p) const
        -> decltype(std::declval<T *>() != std::declval<U *>(), bool()) {
        return _refBase != p._refBase;
    }

#if !defined(doxygen)
    template <class U>
#endif
    auto operator<(const TfRefPtr<U>& p) const
        -> decltype(std::declval<T *>() < std::declval<U *>(), bool()) {
        return _refBase < p._refBase;
    }

#if !defined(doxygen)
    template <class U>
#endif
    auto operator>(const TfRefPtr<U>& p) const
        -> decltype(std::declval<T *>() > std::declval<U *>(), bool()) {
        return _refBase > p._refBase;
    }

#if !defined(doxygen)
    template <class U>
#endif
    auto operator<=(const TfRefPtr<U>& p) const
        -> decltype(std::declval<T *>() <= std::declval<U *>(), bool()) {
        return _refBase <= p._refBase;
    }

#if !defined(doxygen)
    template <class U>
#endif
    auto operator>=(const TfRefPtr<U>& p) const
        -> decltype(std::declval<T *>() >= std::declval<U *>(), bool()) {
        return _refBase >= p._refBase;
    }

    T* operator->() const {
        if (_refBase) {
            return static_cast<T*>(const_cast<TfRefBase*>(_refBase));
        }
        Tf_PostNullSmartPtrDereferenceFatalError(
            TF_CALL_CONTEXT, typeid(TfRefPtr).name());
    }

    T& operator *() const {
        return *operator->();
    }

#if !defined(doxygen)
    using UnspecifiedBoolType = const TfRefBase * (TfRefPtr::*);
#endif

    operator UnspecifiedBoolType() const {
        return _refBase ? &TfRefPtr::_refBase : nullptr;
    }

    bool operator !() const {
        return _refBase == nullptr;
    }

    void swap(TfRefPtr &other) {
        Tf_RefPtrTracker_Assign(this, other._GetObjectForTracking(),
                                _GetObjectForTracking());
        Tf_RefPtrTracker_Assign(&other, _GetObjectForTracking(),
                                other._GetObjectForTracking());
        std::swap(_refBase, other._refBase);
    }

    void Reset() {
        *this = TfNullPtr;
    }        

private:
    const TfRefBase* _refBase;
    
    template <class HashState, class U>
    friend inline void TfHashAppend(HashState &, const TfRefPtr<U>&);
    template <class U>
    friend inline size_t hash_value(const TfRefPtr<U>&);

    friend T *get_pointer(TfRefPtr const &p) {
        return static_cast<T *>(const_cast<TfRefBase *>(p._refBase));
    }

    // Used to distinguish construction in TfCreateRefPtr.
    class _CreateRefPtr { };

    // private constructor, used by TfCreateRefPtr()
    TfRefPtr(T* ptr, _CreateRefPtr /* unused */)
        : _refBase(ptr)
    {
        /* reference count is NOT bumped */
        Tf_RefPtrTracker_FirstRef(this, _GetObjectForTracking());
        Tf_RefPtrTracker_New(this, _GetObjectForTracking());
    }

    // Hide confusing internals of actual C++ definition (e.g. DataType)
    // for doxygen output:

#if defined(doxygen)
    // Sanitized for documentation:
    template <class D>
    friend inline TfRefPtr<D> TfDynamic_cast(const TfRefPtr<T>&);
#else
    template <class D, class B>
    friend TfRefPtr<typename D::DataType>
    TfDynamic_cast(const TfRefPtr<B>&);

    template <class D, class B>
    friend TfRefPtr<typename D::DataType>
    TfSafeDynamic_cast(const TfRefPtr<B>&);
#endif

#if defined(doxygen)
    // Sanitized for documentation:
    template <class D>
    friend inline TfRefPtr<D> TfStatic_cast(const TfRefPtr<T>&);
#else
    template <class D, class B>
    friend TfRefPtr<typename D::DataType>
    TfStatic_cast(const TfRefPtr<B>&);

#endif

#if defined(doxygen)
    // Sanitized for documentation:
    template <class D>
    friend inline TfRefPtr<D> TfConst_cast(const TfRefPtr<const D>&);
#else
    template <class D>
    friend TfRefPtr<typename D::DataType>
    TfConst_cast(const TfRefPtr<const typename D::DataType>&);
#endif

    T* _GetData() const {
        return static_cast<T*>(const_cast<TfRefBase*>(_refBase));
    }
    
    // This method is only used when calling the hook functions for
    // tracking.  We reinterpret_cast instead of static_cast so that
    // we don't need the definition of T.  However, if TfRefBase is
    // not the first base class of T then the resulting pointer may
    // not point to a T.  Nevertheless, it should be consistent to
    // all calls to the tracking functions.
    T* _GetObjectForTracking() const {
        return reinterpret_cast<T*>(const_cast<TfRefBase*>(_refBase));
    }


    template <class U>
    friend const std::type_info& TfTypeid(const TfRefPtr<U>& ptr);

    void _AddRef() const {
        _Counter::AddRef(_refBase);
    }

    void _RemoveRef(const TfRefBase* ptr) const {
        if (_Counter::RemoveRef(ptr)) {
            Tf_RefPtrTracker_LastRef(this,
                reinterpret_cast<T*>(const_cast<TfRefBase*>(ptr)));
            delete ptr;
        }
    }

#if ! defined(doxygen)
    // doxygen is very confused by this. It declares all TfRefPtrs
    // to be friends.
    template <class U> friend class TfRefPtr;
    template <class U> friend class TfWeakPtr;
    friend class Tf_Remnant;

    template <class U>
    friend TfRefPtr<U> TfCreateRefPtrFromProtectedWeakPtr(TfWeakPtr<U> const &);
#endif
    friend class TfWeakBase;
};

#if !defined(doxygen)

//
// nullptr comparisons
//
// These are provided to avoid ambiguous overloads due to
// TfWeakPtrFacade::Derived comparisons with TfRefPtr.
//

template <class T>
inline bool operator== (const TfRefPtr<T> &p, std::nullptr_t)
{
    return !p;
}
template <class T>
inline bool operator== (std::nullptr_t, const TfRefPtr<T> &p)
{
    return !p;
}

template <class T>
inline bool operator!= (const TfRefPtr<T> &p, std::nullptr_t)
{
    return !(p == nullptr);
}
template <class T>
inline bool operator!= (std::nullptr_t, const TfRefPtr<T> &p)
{
    return !(nullptr == p);
}

template <class T>
inline bool operator< (const TfRefPtr<T> &p, std::nullptr_t)
{
    return std::less<const TfRefBase *>()(get_pointer(p), nullptr);
}
template <class T>
inline bool operator< (std::nullptr_t, const TfRefPtr<T> &p)
{
    return std::less<const TfRefBase *>()(nullptr, get_pointer(p));
}

template <class T>
inline bool operator<= (const TfRefPtr<T> &p, std::nullptr_t)
{
    return !(nullptr < p);
}
template <class T>
inline bool operator<= (std::nullptr_t, const TfRefPtr<T> &p)
{
    return !(p < nullptr);
}

template <class T>
inline bool operator> (const TfRefPtr<T> &p, std::nullptr_t)
{
    return nullptr < p;
}
template <class T>
inline bool operator> (std::nullptr_t, const TfRefPtr<T> &p)
{
    return p < nullptr;
}

template <class T>
inline bool operator>= (const TfRefPtr<T> &p, std::nullptr_t)
{
    return !(p < nullptr);
}
template <class T>
inline bool operator>= (std::nullptr_t, const TfRefPtr<T> &p)
{
    return !(nullptr < p);
}


template <typename T>
inline TfRefPtr<T> TfCreateRefPtr(T* ptr) {
    return TfRefPtr<T>(ptr, typename TfRefPtr<T>::_CreateRefPtr());
}

template <class T>
const std::type_info&
TfTypeid(const TfRefPtr<T>& ptr)
{
    if (ARCH_UNLIKELY(!ptr._refBase))
        TF_FATAL_ERROR("called TfTypeid on NULL TfRefPtr");

    return typeid(*ptr._GetData());
}

template <class D, class T>
inline
TfRefPtr<typename D::DataType>
TfDynamic_cast(const TfRefPtr<T>& ptr)
{
    typedef TfRefPtr<typename D::DataType> RefPtr;
    return RefPtr(dynamic_cast<typename D::DataType*>(ptr._GetData()));
}

template <class D, class T>
inline
TfRefPtr<typename D::DataType>
TfSafeDynamic_cast(const TfRefPtr<T>& ptr)
{
    typedef TfRefPtr<typename D::DataType> RefPtr;
    return RefPtr(TfSafeDynamic_cast<typename D::DataType*>(ptr._GetData()));
}

template <class D, class T>
inline
TfRefPtr<typename D::DataType>
TfStatic_cast(const TfRefPtr<T>& ptr)
{
    typedef TfRefPtr<typename D::DataType> RefPtr;
    return RefPtr(static_cast<typename D::DataType*>(ptr._GetData()));
}

template <class T>
inline
TfRefPtr<typename T::DataType>
TfConst_cast(const TfRefPtr<const typename T::DataType>& ptr)
{
    // this ugly cast allows TfConst_cast to work without requiring
    // a definition for T.
    typedef TfRefPtr<typename T::DataType> NonConstRefPtr;
    return *((NonConstRefPtr*)(&ptr));
}

// Specialization: prevent construction of a TfRefPtr<TfRefBase>.

template <>
class TfRefPtr<TfRefBase> {
private:
    TfRefPtr<TfRefBase>() {
    }
};

template <>
class TfRefPtr<const TfRefBase> {
private:
    TfRefPtr<const TfRefBase>() {
    }
};

template <class T>
struct TfTypeFunctions<TfRefPtr<T> > {
    static T* GetRawPtr(const TfRefPtr<T>& t) {
        return t.operator-> ();
    }

    static TfRefPtr<T> ConstructFromRawPtr(T* ptr) {
        return TfRefPtr<T>(ptr);
    }
    
    static bool IsNull(const TfRefPtr<T>& t) {
        return !t;
    }

    static void Class_Object_MUST_Be_Passed_By_Address() { }
    static void Class_Object_MUST_Not_Be_Const() { }
};

template <class T>
struct TfTypeFunctions<TfRefPtr<const T> > {
    static const T* GetRawPtr(const TfRefPtr<const T>& t) {
        return t.operator-> ();
    }

    static TfRefPtr<const T> ConstructFromRawPtr(T* ptr) {
        return TfRefPtr<const T>(ptr);
    }

    static bool IsNull(const TfRefPtr<const T>& t) {
        return !t;
    }

    static void Class_Object_MUST_Be_Passed_By_Address() { }
};

#endif

#if !defined(doxygen)

template <class T>
inline void
swap(TfRefPtr<T>& lhs, TfRefPtr<T>& rhs)
{
    lhs.swap(rhs);
}

PXR_NAMESPACE_CLOSE_SCOPE

namespace boost {

template<typename T>
T *
get_pointer(PXR_NS::TfRefPtr<T> const& p)
{
    return get_pointer(p);
}

} // end namespace boost

PXR_NAMESPACE_OPEN_SCOPE

// Extend boost::hash to support TfRefPtr.
template <class T>
inline size_t
hash_value(const TfRefPtr<T>& ptr)
{
    // Make the boost::hash type depend on T so that we don't have to always
    // include boost/functional/hash.hpp in this header for the definition of
    // boost::hash.
    auto refBase = ptr._refBase;
    return boost::hash<decltype(refBase)>()(refBase);
}

template <class HashState, class T>
inline void
TfHashAppend(HashState &h, const TfRefPtr<T> &ptr)
{
    h.Append(get_pointer(ptr));
}

#endif // !doxygen

#define TF_SUPPORTS_REFPTR(T) std::is_base_of<TfRefBase, T>::value

#if defined(ARCH_COMPILER_MSVC) 
// There is a bug in the compiler which means we have to provide this
// implementation. See here for more information:
// https://connect.microsoft.com/VisualStudio/Feedback/Details/2852624

#define TF_REFPTR_CONST_VOLATILE_GET(x)                                       \
        namespace boost                                                       \
        {                                                                     \
            template<>                                                        \
            const volatile x*                                                 \
                get_pointer(const volatile x* p)                              \
            {                                                                 \
                return p;                                                     \
            }                                                                 \
        }
#else
#define TF_REFPTR_CONST_VOLATILE_GET(x)
#endif

PXR_NAMESPACE_CLOSE_SCOPE

#endif // PXR_BASE_TF_REF_PTR_H