valueRef.h

//
// Copyright 2025 Pixar
//
// Licensed under the terms set forth in the LICENSE.txt file available at
// https://openusd.org/license.
//
#ifndef PXR_BASE_VT_VALUEREF_H
#define PXR_BASE_VT_VALUEREF_H
 
#include "pxr/pxr.h"
 
// XXX: Include pyLock.h after pyObjWrapper.h to work around
// Python include ordering issues.
#include "pxr/base/tf/pyObjWrapper.h"
 
#include "pxr/base/tf/pyLock.h"
 
#include "pxr/base/arch/demangle.h"
#include "pxr/base/arch/hints.h"
#include "pxr/base/arch/pragmas.h"
#include "pxr/base/tf/anyUniquePtr.h"
#include "pxr/base/tf/preprocessorUtilsLite.h"
#include "pxr/base/tf/safeTypeCompare.h"
#include "pxr/base/tf/stringUtils.h"
#include "pxr/base/tf/tf.h"
#include "pxr/base/tf/type.h"
 
#include "pxr/base/vt/api.h"
#include "pxr/base/vt/hash.h"
#include "pxr/base/vt/streamOut.h"
#include "pxr/base/vt/traits.h"
#include "pxr/base/vt/types.h"
#include "pxr/base/vt/valueCommon.h"
 
#include <iosfwd>
#include <typeinfo>
#include <type_traits>
 
PXR_NAMESPACE_OPEN_SCOPE
 
class VtValue;
class VtValueRef;
 
// Overload VtStreamOut for vector<VtValueRef>.  Produces output like [value1,
// value2, ... valueN].
VT_API std::ostream &
VtStreamOut(std::vector<VtValueRef> const &val, std::ostream &);
 
class VtValueRef
{
protected:
 
    // This unfortunately needs to be a union since there are some callers that
    // place function pointers in VtValue.  The specific _TypeInfo
    // instantiations know which union member to use at based on their type
    // parameter.
    union _RefdObjPtr {
        void const *objPtr;
        void (*fnPtr)();
    };
    
    // Type information base class.
    // We force alignment here in order to ensure that TfPointerAndBits has
    // enough room to store all TypeInfo related flags.
    struct alignas(8) _TypeInfo {
    private:
        using _CanHashFunc = bool (*)(_RefdObjPtr);
        using _HashFunc = size_t (*)(_RefdObjPtr);
        using _EqualFunc = bool (*)(_RefdObjPtr, _RefdObjPtr);
        using _GetPyObjFunc = TfPyObjWrapper (*)(_RefdObjPtr);
        using _GetVtValueFunc = VtValue (*)(_RefdObjPtr);
        using _StreamOutFunc = std::ostream & (*)(_RefdObjPtr, std::ostream &);
        using _IsArrayValuedFunc = bool (*)(_RefdObjPtr);
        using _GetNumElementsFunc = size_t (*)(_RefdObjPtr);
 
    protected:
        constexpr _TypeInfo(const std::type_info &ti,
                            const std::type_info &elementTi,
                            int knownTypeIndex,
                            bool isArray,
                            bool isHashable,
                            bool canComposeOver,
                            bool canTransform,
                            bool isMutable,
                            _CanHashFunc canHash,
                            _HashFunc hash,
                            _EqualFunc equal,
                            _GetPyObjFunc getPyObj,
                            _GetVtValueFunc getVtValue,
                            _StreamOutFunc streamOut,
                            _IsArrayValuedFunc isArrayValued,
                            _GetNumElementsFunc getNumElements)
            : typeInfo(ti)
            , elementTypeInfo(elementTi)
            , knownTypeIndex(knownTypeIndex)
            , isArray(isArray)
            , isHashable(isHashable)
            , canComposeOver(canComposeOver)
            , canTransform(canTransform)
            , isMutable(isMutable)
            // Function table
            , _canHash(canHash)
            , _hash(hash)
            , _equal(equal)
            , _getPyObj(getPyObj)
            , _getVtValue(getVtValue)
            , _streamOut(streamOut)
            , _isArrayValued(isArrayValued)
            , _getNumElements(getNumElements)
        {}
 
    public:
        bool CanHash(_RefdObjPtr storage) const {
            return _canHash(storage);
        }
        size_t Hash(_RefdObjPtr storage) const {
            return _hash(storage);
        }
        bool Equal(_RefdObjPtr lhs, _RefdObjPtr rhs) const {
            return _equal(lhs, rhs);
        }
        TfPyObjWrapper GetPyObj(_RefdObjPtr storage) const {
            return _getPyObj(storage);
        }
        // Defined below due to circular VtValue <-> VtValueRef includes.
        inline VtValue GetVtValue(_RefdObjPtr storage) const;
        std::ostream &StreamOut(_RefdObjPtr storage,
                                std::ostream &out) const {
            return _streamOut(storage, out);
        }
        bool IsArrayValued(_RefdObjPtr storage) const {
            return _isArrayValued(storage);
        }
        size_t GetNumElements(_RefdObjPtr storage) const {
            return _getNumElements(storage);
        }
 
        const std::type_info &typeInfo;
        const std::type_info &elementTypeInfo;
        const int knownTypeIndex;
        const bool isArray;
        const bool isHashable;
        const bool canComposeOver;
        const bool canTransform;
        const bool isMutable;
 
    private:
        _CanHashFunc _canHash;
        _HashFunc _hash;
        _EqualFunc _equal;
        _GetPyObjFunc _getPyObj;
        _GetVtValueFunc _getVtValue;
        _StreamOutFunc _streamOut;
        _IsArrayValuedFunc _isArrayValued;
        _GetNumElementsFunc _getNumElements;
    };
 
    // Type-dispatching overloads.
 
    // Array type helpers.  Non-array types have no shape data, no elements and
    // report `void` for their element types.
    template <class T>
    struct _NonArrayHelper
    {
        template <class U>
        static size_t GetNumElements(U &&) { return 0; }
        constexpr static std::type_info const &GetElementTypeid() {
            return typeid(void);
        }
    };
    // VtArray types report their qualities.
    template <class Array>
    struct _IsArrayHelper
    {
        static size_t GetNumElements(Array const &obj) {
            return obj.size();
        }
        constexpr static std::type_info const &GetElementTypeid() {
            return typeid(typename Array::ElementType);
        }
    };
    // VtArrayEdit types are identical to non-array types except that they do
    // report their underlying element type.
    template <class ArrayEdit>
    struct _IsArrayEditHelper : _NonArrayHelper<ArrayEdit>
    {
        constexpr static std::type_info const &GetElementTypeid() {
            return typeid(typename ArrayEdit::ElementType);
        }
    };
 
    // Select which flavor of array helper to use -- VtArray uses
    // _IsArrayHelper, VtArrayEdit uses _IsArrayEditHelper, all other types use
    // _NonArrayHelper.
    template <class T>
    using _ArrayHelper = TfConditionalType<
        VtIsArray<T>::value, _IsArrayHelper<T>,
        TfConditionalType<VtIsArrayEdit<T>::value,
                          _IsArrayEditHelper<T>, _NonArrayHelper<T>>
        >;
 
    // _TypeInfo implementation.
    template <class T, bool IsMutable>
    struct _TypeInfoImpl : public _TypeInfo
    {
        using Type = T;
        using This = _TypeInfoImpl;
 
        static constexpr bool IsPointer = std::is_pointer_v<Type>;
        static constexpr bool IsFunctionPointer =
            IsPointer && std::is_function_v<std::remove_pointer_t<Type>>;
        
        using ConstType = std::conditional_t<
            IsPointer,
            const std::remove_pointer_t<Type> *,
            const Type>;
 
        using GetObjResultType = std::conditional_t<
            IsPointer, ConstType, ConstType &>;
 
        using GetMutableObjResultType = std::conditional_t<
            IsPointer, Type, Type &>;
        
        //using RefType = Type &;
        // using ObjType = std::conditional_t<
        //     std::is_pointer_v<Type>, Type, Type &>;
        //using ConstRefType = ConstType const &;
 
        constexpr _TypeInfoImpl()
            : _TypeInfo(typeid(T),
                        _ArrayHelper<T>::GetElementTypeid(),
                        Vt_KnownValueTypeDetail::GetIndex<T>(),
                        VtIsArray<T>::value,
                        VtIsHashable<T>(),
                        VtValueTypeCanCompose<T>::value,
                        VtValueTypeCanTransform<T>::value,
                        IsMutable,
                        &This::_CanHash,
                        &This::_Hash,
                        &This::_Equal,
                        &This::_GetPyObj,
                        &This::_GetVtValue,
                        &This::_StreamOut,
 
                        // Array support.
                        &This::_IsArrayValued,
                        &This::_GetNumElements)
 
        {}
 
        // Typed API for client use.
        static GetObjResultType
        GetObj(_RefdObjPtr const &storage) {
            if constexpr (IsFunctionPointer) {
                return reinterpret_cast<GetObjResultType>(storage.fnPtr);
            }
            else if constexpr (IsPointer) {
                return reinterpret_cast<GetObjResultType>(storage.objPtr);
            }
            else {
                return *static_cast<ConstType *>(storage.objPtr);
            }
        }
 
        static GetMutableObjResultType
        GetMutableObj(_RefdObjPtr &storage) {
            // This const cast is safe since the original VtValueRef must've
            // been constructed with a mutable object.
            if constexpr (IsFunctionPointer) {
                return reinterpret_cast<GetMutableObjResultType>(storage.fnPtr);
            }                
            else if constexpr (IsPointer) {
                return reinterpret_cast<
                    GetMutableObjResultType>(storage.objPtr);
            }
            else {
                return *static_cast<Type *>(const_cast<void *>(storage.objPtr));
            }
        }
 
        static void SetObj(T const &obj, _RefdObjPtr &storage) {
            if constexpr (IsFunctionPointer) {
                storage.fnPtr = reinterpret_cast<void (*)()>(obj);
            }
            else if constexpr (IsPointer) {
                storage.objPtr = static_cast<void const *>(obj);
            }
            else {
                storage.objPtr = static_cast<void const *>(std::addressof(obj));
            }
        }
 
    private:
        static bool _CanHash(_RefdObjPtr) {
            return VtIsHashable<T>();
        }
 
        static size_t _Hash(_RefdObjPtr ptr) {
            return VtHashValue(GetObj(ptr));
        }
 
        static bool _Equal(_RefdObjPtr lhs, _RefdObjPtr rhs) {
            return GetObj(lhs) == GetObj(rhs);
        }
 
        static TfPyObjWrapper _GetPyObj(_RefdObjPtr storage) {
#ifdef PXR_PYTHON_SUPPORT_ENABLED
            TfPyLock lock;
            return pxr_boost::python::api::object(GetObj(storage));
#else
            return {};
#endif
        }
 
        // Defined below.
        static VtValue _GetVtValue(_RefdObjPtr storage);
 
        static std::ostream &_StreamOut(
            _RefdObjPtr storage, std::ostream &out) {
            return VtStreamOut(GetObj(storage), out);
        }
 
        static bool _IsArrayValued(_RefdObjPtr storage) {
            return VtIsArray<T>::value;
        }
 
        static std::type_info const &
        _GetElementTypeid(_RefdObjPtr ptr) {
            return _ArrayHelper<T>::GetElementTypeid();
        }
 
        static size_t _GetNumElements(_RefdObjPtr ptr) {
            return _ArrayHelper<T>::GetNumElements(GetObj(ptr));
        }
 
    };
 
    // Metafunction that returns the specific _TypeInfo subclass for T or T&.
    // The passed `T` should be as-if deduced by a forwarding reference, so a
    // reference type if the referenced object is mutable, otherwise a
    // non-reference type.
    template <class T>
    using _TypeInfoFor = _TypeInfoImpl<
        std::decay_t<T>,
        std::is_reference_v<T> && std::is_const_v<T>>;
 
public:
 
    VtValueRef() : _info(nullptr) {}
 
    VtValueRef(VtValueRef const &) = default;
    VtValueRef(VtValueRef &&) = default;
 
    template <class T>
    VtValueRef(T &&obj, std::enable_if_t<
               !std::is_same_v<std::decay_t<T>, VtValueRef> &&
               !std::is_same_v<std::decay_t<T>, VtValue>> * = 0) {
        using TypeInfo = _TypeInfoFor<T>;
        using TypeInfoType = typename TypeInfo::Type;
        static_assert(!VtIsValueProxy<TypeInfoType>::value,
                      "VtValueRef does not support proxies");
        static const TypeInfo ti;
        ti.SetObj(obj, _ptr);
        _info = std::addressof(ti);
    }
 
    VtValueRef &operator=(VtValueRef const &ref) = default;
    VtValueRef &operator=(VtValueRef &&ref) = default;
 
    // Disallow implicit conversion assignments.
    template <class T>
    VtValueRef &operator=(T &&) = delete;
 
    friend void swap(VtValueRef &lhs, VtValueRef &rhs) {
        std::swap(lhs._ptr, rhs._ptr);
        std::swap(lhs._info, rhs._info);
    }
 
    template <class T>
    bool IsHolding() const {
        return _info && _TypeIs<T>();
    }
 
    bool IsRValue() const {
        return _info && _info->isMutable;
    }
 
    VT_API bool IsArrayValued() const;
 
    VT_API bool IsArrayEditValued() const;
 
    size_t GetArraySize() const { return _GetNumElements(); }
 
    std::type_info const &GetTypeid() const {
        return _info ? _info->typeInfo : typeid(void);
    }
 
    std::type_info const &GetElementTypeid() const {
        return _info ? _info->elementTypeInfo : typeid(void);
    }
    
    VT_API TfType GetType() const;
 
    VT_API std::string GetTypeName() const;
 
    int GetKnownValueTypeIndex() const {
        return _info ? _info->knownTypeIndex : -1;
    }
 
    template <class T>
    typename _TypeInfoFor<T>::GetObjResultType
    UncheckedGet() const { return _Get<T>(); }
 
    template <class T>
    typename _TypeInfoFor<T>::GetObjResultType
    Get() const {
        using Factory = Vt_DefaultValueFactory<T>;
 
        // In the unlikely case that the types don't match, we obtain a default
        // value to return and issue an error via _FailGet.
        if (ARCH_UNLIKELY(!IsHolding<T>())) {
            return *(static_cast<T const *>(
                         _FailGet(Factory::Invoke, typeid(T))));
        }
 
        return _Get<T>();
    }
 
    template <class T>
    T GetWithDefault(T const &def = T()) const {
        return IsHolding<T>() ? UncheckedGet<T>() : def;
    }
 
    template <class T>
    T Remove() {
        if (IsHolding<T>()) {
            return UncheckedRemove<T>();
        }
        else {
            _FailRemove(typeid(T));
        }
        return {};
    }
 
    template <class T>
    T UncheckedRemove() {
        if (IsRValue()) {
            return std::move(_GetMutable<T>());
        }
        return _Get<T>();
    }
 
    bool IsEmpty() const { return !_info; }
 
    VT_API operator VtValue() const;
 
    VT_API bool CanHash() const;
 
    VT_API size_t GetHash() const;
 
    friend inline size_t hash_value(VtValueRef const &val) {
        return val.GetHash();
    }
 
    bool CanComposeOver() const {
        return !_info || _info->canComposeOver;
    }
 
    bool CanTransform() const {
        return _info && _info->canTransform;
    }
 
    bool operator == (const VtValueRef &rhs) const {
        bool empty = IsEmpty(), rhsEmpty = rhs.IsEmpty();
        if (empty || rhsEmpty) {
            // Either one or both empty -- only equal if both empty.
            return empty == rhsEmpty;
        }
        if (_info == rhs._info) {
            // Holding identical types -- compare directly.
            return _info->Equal(_ptr, rhs._ptr);
        }
        return false;
    }
    bool operator != (const VtValueRef &rhs) const { return !(*this == rhs); }
 
    VT_API friend std::ostream &
    operator << (std::ostream &out, const VtValueRef &self);
 
protected:    
    VT_API size_t _GetNumElements() const;
 
    template <class T>
    inline bool
    _TypeIs() const {
        if constexpr (VtIsKnownValueType_Workaround<T>::value) {
            return _info->knownTypeIndex == VtGetKnownValueTypeIndex<T>();
        }
        else {
            std::type_info const &t = typeid(T);
            return TfSafeTypeCompare(_info->typeInfo, t);
        }
    }
 
    template <class T>
    typename _TypeInfoFor<T>::GetMutableObjResultType
    _GetMutable() {
        using TypeInfo = _TypeInfoFor<T>;
        return TypeInfo::GetMutableObj(_ptr);
    }
 
    template <class T>
    typename _TypeInfoFor<T>::GetObjResultType
    _Get() const {
        using TypeInfo = _TypeInfoFor<T>;
        return TypeInfo::GetObj(_ptr);
    }
 
    // Helper invoked in case Get fails.  Reports an error and returns a default
    // value for \a queryType.
    VT_API void const *
    _FailGet(Vt_DefaultValueHolder (*factory)(),
             std::type_info const &queryType) const;
 
    VT_API void _FailRemove(std::type_info const &);
 
    // This grants friend access to a function in the wrapper file for this
    // class.  This lets the wrapper reach down into a value to get a
    // pxr_boost::python wrapped object corresponding to the viewed type.  This
    // facility is necessary to get the python API we want.
    friend TfPyObjWrapper
    Vt_GetPythonObjectFromHeldValue(VtValueRef const &self);
 
    VT_API TfPyObjWrapper _GetPythonObject() const;
 
    _RefdObjPtr _ptr;
    _TypeInfo const *_info;
};
 
#ifndef doxygen
 
//
// The Get()/IsHolding routines needs to be special-cased to handle getting a
// VtValueRef *as* a VtValueRef.
//
 
template <>
inline VtValueRef const &
VtValueRef::Get<VtValueRef>() const {
    return *this;
}
 
template <>
inline VtValueRef const &
VtValueRef::UncheckedGet<VtValueRef>() const {
    return *this;
}
 
template <>
inline bool
VtValueRef::IsHolding<VtValueRef>() const {
    return true;
}
 
// Specialize VtValueRef::IsHolding<void>() to always return false.
template <>
inline bool
VtValueRef::IsHolding<void>() const {
    return false;
}
 
#endif // !doxygen
 
class VtMutableValueRef : public VtValueRef
{
public:
    VtMutableValueRef() = default;
 
    template <class T>
    VtMutableValueRef(T &obj) : VtValueRef(obj) {}
 
    template <class T>
    VtMutableValueRef &operator=(T &&obj) {
        static_assert(std::is_same_v<T, typename Vt_ValueGetStored<T>::Type>,
                      "Can only assign to VtMutableValueRef with a type T "
                      "that stores as T");
        if (IsHolding<T>()) {
            _GetMutable<T>() = std::forward<T>(obj);
        }
        else {
            _FailAssign(typeid(T));
        }
        return *this;
    }
 
    template <class T>
    VtMutableValueRef &UncheckedAssign(T &&obj) {
        static_assert(std::is_same_v<T, typename Vt_ValueGetStored<T>::Type>,
                      "Can only assign to VtMutableValueRef with a type T "
                      "that stores as T");
        _GetMutable<T>() = std::forward<T>(obj);
        return *this;
    }
 
    template <class T>
    void
    Swap(T &rhs) {
        static_assert(std::is_same_v<T, typename Vt_ValueGetStored<T>::Type>,
                      "Can only VtValueRef::Swap with a type T "
                      "that stores as T");
        if (IsHolding<T>()) {
            UncheckedSwap(rhs);
        }
        else {
            _FailSwap(typeid(T));
        }
    }
 
    template <class T>
    void
    UncheckedSwap(T &rhs) {
        static_assert(std::is_same_v<T, typename Vt_ValueGetStored<T>::Type>,
                      "Can only VtValueRef::Swap with a type T "
                      "that stores as T");
        using std::swap;
        swap(_GetMutable<T>(), rhs);
    }
 
    template <class T, class Fn>
    bool
    Mutate(Fn &&mutateFn) {
        static_assert(std::is_same_v<T, typename Vt_ValueGetStored<T>::Type>,
                      "Can only VtValueRef::Mutate a type T that stores as T");
        if (!IsHolding<T>()) {
            return false;
        }
        UncheckedMutate<T>(std::forward<Fn>(mutateFn));
        return true;
    }
 
    template <class T, class Fn>
    void
    UncheckedMutate(Fn &&mutateFn) {
        static_assert(std::is_same_v<T, typename Vt_ValueGetStored<T>::Type>,
                      "Can only VtValueRef::Mutate a type T that stores as T");
        // We move to a temporary, mutate the temporary, then move back.  This
        // prevents callers from escaping a mutable reference to the viewed
        // object via a side-effect of mutateFn.
        T &stored = _GetMutable<T>();
        T tmp = std::move(stored);
        std::forward<Fn>(mutateFn)(tmp);
        stored = std::move(tmp);
    }
 
private:
    VT_API void _FailAssign(std::type_info const &);
    VT_API void _FailSwap(std::type_info const &);
 
};
 
PXR_NAMESPACE_CLOSE_SCOPE
 
// This unusual arrangement of closing the namespace, including value.h, then
// reopening the namespace exists because valueRef.h and value.h are
// interdependent.  A similar symmetric construct exists in value.h.  If
// valueRef.h is included first, then value.h will be included here.  Otherwise
// if value.h is included first then it will have included valueRef.h.  Either
// way all the necessary declarations from both types are present prior to the
// appearance of the following defintions.
 
#include "pxr/base/vt/value.h"
 
PXR_NAMESPACE_OPEN_SCOPE
 
// Defined here due to circular dependencies.
VtValue
VtValueRef::_TypeInfo::GetVtValue(_RefdObjPtr storage) const {
    return _getVtValue(storage);
}
 
template <class T, bool B>
VtValue
VtValueRef::_TypeInfoImpl<T, B>::_GetVtValue(_RefdObjPtr storage) {
    return VtValue { GetObj(storage) };
}
 
PXR_NAMESPACE_CLOSE_SCOPE
 
#ifdef PXR_PYTHON_SUPPORT_ENABLED
 
#include "pxr/external/boost/python/converter/arg_from_python.hpp"
#include <optional>
 
namespace PXR_BOOST_NAMESPACE::python::converter {
 
// We specialize arg_rvalue_from_python<VtValueRef> to derive
// arg_rvalue_from_python<VtValue>.  This way we get storage for both -- an
// `rvalue_from_python_data<VtValue &> m_data` in the base and a VtValueRef in
// this class.  There's no other way afaict to "add space" in an rvalue
// converter to support a "view" type where we need to also conjure a temporary
// for that view.  This way we can create the `VtValue` in the base as usual and
// let the `VtValueRef` here refer to it for the lifetime of the arg.
template <>
struct arg_rvalue_from_python<PXR_NS::VtValueRef>
    : public arg_rvalue_from_python<PXR_NS::VtValue>
{
    using base_type = arg_rvalue_from_python<PXR_NS::VtValue>;
    using base_type::convertible;
    using result_type = PXR_NS::VtValueRef &; // boost.python convention.
 
    VT_API arg_rvalue_from_python(PyObject* obj);
 
    VT_API result_type operator()();
    
    std::optional<PXR_NS::VtValueRef> optValueRef;
};
 
} // namespace PXR_BOOST_NAMESPACE::python::converter
 
#endif // PXR_PYTHON_SUPPORT_ENABLED
 
#endif // PXR_BASE_VT_VALUEREF_H