WeakObjectPtr.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
/*=============================================================================
    WeakObjectPtr.h: Weak pointer to UObject
=============================================================================*/
 
#pragma once
 
#include "CoreTypes.h"
#include "Misc/AssertionMacros.h"
#include "Templates/UnrealTemplate.h"
#include "UObject/ScriptDelegates.h"
#include "UObject/UObjectArray.h"
#include "UObject/StrongObjectPtr.h"
#include "UObject/WeakObjectPtrFwd.h"
#include "UObject/ObjectHandleDefines.h"
#include "UObject/RemoteObjectTypes.h"
#include <type_traits>
 
class FArchive;
class UObject;
template <class, class>
struct TWeakObjectPtr;
 
#ifndef UE_WEAKOBJECTPTR_ZEROINIT_FIX
    #define UE_WEAKOBJECTPTR_ZEROINIT_FIX 1
#endif
 
namespace UE::Core::Private
{
#if UE_WEAKOBJECTPTR_ZEROINIT_FIX
    inline constexpr int32 InvalidWeakObjectIndex = 0;
#else
    inline constexpr int32 InvalidWeakObjectIndex = INDEX_NONE;
#endif
}
 
struct FWeakObjectPtr
{
public:
 
    template <class, class>
    friend struct TWeakObjectPtr;
 
#if UE_WEAKOBJECTPTR_ZEROINIT_FIX
    FWeakObjectPtr() = default;
 
    UE_FORCEINLINE_HINT FWeakObjectPtr(TYPE_OF_NULLPTR)
        : FWeakObjectPtr()
    {
    }
#else
    UE_FORCEINLINE_HINT FWeakObjectPtr()
    {
        Reset();
    }
 
    UE_FORCEINLINE_HINT FWeakObjectPtr(TYPE_OF_NULLPTR)
    {
        (*this) = nullptr;
    }
#endif
 
    UE_DEPRECATED(5.6, "Constructing a FWeakObjectPtr from NULL has been deprecated - please use nullptr instead.")
    UE_FORCEINLINE_HINT FWeakObjectPtr(int)
    {
        (*this) = nullptr;
    }
 
    UE_FORCEINLINE_HINT FWeakObjectPtr(FObjectPtr Object)
    {
        *this = Object;
    }
    UE_FORCEINLINE_HINT FWeakObjectPtr(const UObject* Object)
        : FWeakObjectPtr(FObjectPtr(const_cast<UObject*>(Object)))
    {
    }
    template <typename T>
    UE_FORCEINLINE_HINT FWeakObjectPtr(TObjectPtr<T> Object)
        : FWeakObjectPtr(FObjectPtr(const_cast<UObject*>(ImplicitConv<const UObject*>(Object.Get()))))
    {
        // This needs to be a template instead of TObjectPtr<const UObject> because C++ does derived-to-base
        // pointer conversions ('standard conversion sequences') in situations that TSmartPtr<Derived>-to-TSmartPtr<Base>
        // conversions ('user-defined conversions') doesn't, meaning it won't auto-convert in many real use cases.
        //
        // https://en.cppreference.com/w/cpp/language/implicit_conversion
    }
 
    FWeakObjectPtr(const FWeakObjectPtr& Other) = default;
 
#if UE_WITH_REMOTE_OBJECT_HANDLE
    explicit FWeakObjectPtr(FRemoteObjectId RemoteId)
    {
        // When using remote object handles both ObjectIndex and SerialNumber are not used when comparing weak object pointers
        // ObjectIndex is used for performance only and will be updated when this weak pointer is accessed
        // SerialNumber will also get updated when this weak pointer is resolved
        ObjectIndex = 0;        
        ObjectSerialNumber = 0;
        ObjectRemoteId = RemoteId;
    }
#endif // UE_WITH_REMOTE_OBJECT_HANDLE
 
    inline void Reset()
    {
        using namespace UE::Core::Private;
 
        ObjectIndex = InvalidWeakObjectIndex;
        ObjectSerialNumber = 0;
#if UE_WITH_REMOTE_OBJECT_HANDLE
        ObjectRemoteId = FRemoteObjectId();
#endif
    }
 
    COREUOBJECT_API void operator=(FObjectPtr Object);
    UE_FORCEINLINE_HINT void operator=(const UObject* Object)
    {
        *this = FObjectPtr(const_cast<UObject*>(Object));
    }
    template <typename T>
    UE_FORCEINLINE_HINT void operator=(TObjectPtr<T> Object)
    {
        // This needs to be a template instead of TObjectPtr<const UObject> because C++ does derived-to-base
        // pointer conversions ('standard conversion sequences') in situations that TSmartPtr<Derived>-to-TSmartPtr<Base>
        // conversions ('user-defined conversions') doesn't, meaning it won't auto-convert in many real use cases.
        //
        // https://en.cppreference.com/w/cpp/language/implicit_conversion
 
        *this = FObjectPtr(Object);
    }
 
    FWeakObjectPtr& operator=(const FWeakObjectPtr& Other) = default;
 
    inline bool operator==(const FWeakObjectPtr& Other) const
    {
        return 
#if UE_WITH_REMOTE_OBJECT_HANDLE
            ObjectRemoteId == Other.ObjectRemoteId ||
#else
            (ObjectIndex == Other.ObjectIndex && ObjectSerialNumber == Other.ObjectSerialNumber) ||
#endif
            (!IsValid() && !Other.IsValid());
    }
 
#if !PLATFORM_COMPILER_HAS_GENERATED_COMPARISON_OPERATORS
    inline bool operator!=(const FWeakObjectPtr& Other) const
    {
        return 
#if UE_WITH_REMOTE_OBJECT_HANDLE
            ObjectRemoteId != Other.ObjectRemoteId &&
#else
            (ObjectIndex != Other.ObjectIndex || ObjectSerialNumber != Other.ObjectSerialNumber) &&
#endif
            (IsValid() || Other.IsValid());
    }
#endif
 
    inline bool HasSameIndexAndSerialNumber(const FWeakObjectPtr& Other) const
    {
#if UE_WITH_REMOTE_OBJECT_HANDLE
        return ObjectRemoteId == Other.ObjectRemoteId;
#else
        return ObjectIndex == Other.ObjectIndex && ObjectSerialNumber == Other.ObjectSerialNumber;
#endif
    }
 
    COREUOBJECT_API class UObject* Get(bool bEvenIfGarbage) const;
 
    COREUOBJECT_API class UObject* Get(/*bool bEvenIfGarbage = false*/) const;
 
    COREUOBJECT_API class UObject* GetEvenIfUnreachable() const;
 
    COREUOBJECT_API class TStrongObjectPtr<UObject> Pin(bool bEvenIfGarbage) const;
 
    COREUOBJECT_API class TStrongObjectPtr<UObject> Pin(/*bool bEvenIfGarbage = false*/) const;
 
    /*
     * Get a strong object ptr even if it is marked as Garbage or Unreachable 
     * @return TStrongObjectPtr will be invalid if this object is gone or the weak pointer is explicitly null, otherwise a valid TStrongObjectPtr
     */
    COREUOBJECT_API class TStrongObjectPtr<UObject> PinEvenIfUnreachable() const;
 
 
    COREUOBJECT_API class TStrongObjectPtr<UObject> TryPin(bool& bOutPinValid, bool bEvenIfGarbage) const;
 
    COREUOBJECT_API class TStrongObjectPtr<UObject> TryPin(bool& bOutPinValid /*, bool bEvenIfGarbage = false*/) const;
 
    /*
     * Attempt to get a strong object ptr even if it is marked as Garbage or Unreachable, but only if garbage collection is not in progress
     * @param OutResult will be invalid if this object is gone, or the weak pointer is explicitly null, or garbage collection is in progress. Otherwise a valid TStrongObjectPtr
     * @return  true if garbage collection was not in progress, and OutResult was successfully captured, false if garbage collection was in progress and OutResult was not captured 
     */
    COREUOBJECT_API bool TryPinEvenIfUnreachable(class TStrongObjectPtr<UObject>& OutResult) const;
 
    // This is explicitly not added to avoid resolving weak pointers too often - use Get() once in a function.
    explicit operator bool() const = delete;
 
    COREUOBJECT_API bool IsValid(bool bEvenIfGarbage, bool bThreadsafeTest = false) const;
 
    COREUOBJECT_API bool IsValid(/*bool bEvenIfGarbage = false, bool bThreadsafeTest = false*/) const;
 
    COREUOBJECT_API bool IsStale(bool bIncludingGarbage = true, bool bThreadsafeTest = false) const;
 
    inline bool IsExplicitlyNull() const
    {
        using namespace UE::Core::Private;
#if UE_WITH_REMOTE_OBJECT_HANDLE
        return !ObjectRemoteId.IsValid();
#else
#if UE_WEAKOBJECTPTR_ZEROINIT_FIX
        return ObjectIndex == InvalidWeakObjectIndex && ObjectSerialNumber == 0;
#else
        return ObjectIndex == InvalidWeakObjectIndex;
#endif
#endif // UE_WITH_REMOTE_OBJECT_HANDLE
    }
 
#if UE_WITH_REMOTE_OBJECT_HANDLE
    UE_FORCEINLINE_HINT FRemoteObjectId GetRemoteId() const
    {
        return ObjectRemoteId;
    }
 
    COREUOBJECT_API bool HasSameObject(const UObject* Other) const;
 
    UE_FORCEINLINE_HINT bool IsRemote() const
    {
        return UE::RemoteObject::Handle::IsRemote(ObjectRemoteId);
    }
#else
    UE_FORCEINLINE_HINT bool IsRemote() const
    {
        return false;
    }
#endif // UE_WITH_REMOTE_OBJECT_HANDLE
 
    inline uint32 GetTypeHash() const
    {
#if UE_WITH_REMOTE_OBJECT_HANDLE
        return ::GetTypeHash(ObjectRemoteId);
#else
        return uint32(ObjectIndex ^ ObjectSerialNumber);
#endif
    }
 
    COREUOBJECT_API void Serialize(FArchive& Ar);
 
protected:
    UE_DEPRECATED(5.1, "GetObjectIndex is now deprecated, and will be removed.")
    UE_FORCEINLINE_HINT int32 GetObjectIndex() const
    {
        return ObjectIndex;
    }
 
private:
    inline int32 GetObjectIndex_Private() const
    {
#if UE_WITH_REMOTE_OBJECT_HANDLE
        using namespace UE::Core::Private;
        if ((ObjectIndex == InvalidWeakObjectIndex) && ObjectRemoteId.IsValid())
        {
            TryResolveRemoteObject();
        }
#endif
        return ObjectIndex;
    }
 
private:
    friend struct FObjectKey;
    
#if UE_WITH_REMOTE_OBJECT_HANDLE
    COREUOBJECT_API FUObjectItem* TryResolveRemoteObject() const;
    COREUOBJECT_API bool CanBeResolved() const;
#endif
 
    inline bool SerialNumbersMatch() const
    {
#if UE_WITH_REMOTE_OBJECT_HANDLE
        checkSlow(ObjectIndex >= 0); // otherwise this is a corrupted weak pointer
        FRemoteObjectId ActualId = GUObjectArray.GetRemoteId(ObjectIndex);
        return ActualId == ObjectRemoteId;
#else
        checkSlow(ObjectSerialNumber > FUObjectArray::START_SERIAL_NUMBER && ObjectIndex >= 0); // otherwise this is a corrupted weak pointer
        int32 ActualSerialNumber = GUObjectArray.GetSerialNumber(ObjectIndex);
        checkSlow(!ActualSerialNumber || ActualSerialNumber >= ObjectSerialNumber); // serial numbers should never shrink
        return ActualSerialNumber == ObjectSerialNumber;
#endif
    }
 
    inline bool SerialNumbersMatch(FUObjectItem* ObjectItem) const
    {
#if UE_WITH_REMOTE_OBJECT_HANDLE
        checkSlow(ObjectIndex >= 0); // otherwise this is a corrupted weak pointer
        FRemoteObjectId ActualId = ObjectItem->GetRemoteId();
        return ActualId == ObjectRemoteId;
#else
        checkSlow(ObjectSerialNumber > FUObjectArray::START_SERIAL_NUMBER && ObjectIndex >= 0); // otherwise this is a corrupted weak pointer
        const int32 ActualSerialNumber = ObjectItem->GetSerialNumber();
        checkSlow(!ActualSerialNumber || ActualSerialNumber >= ObjectSerialNumber); // serial numbers should never shrink
        return ActualSerialNumber == ObjectSerialNumber;
#endif
    }
 
    inline FUObjectItem* Internal_GetObjectItem() const
    {
        using namespace UE::Core::Private;
 
#if UE_WITH_REMOTE_OBJECT_HANDLE
        if (IsExplicitlyNull())
        {
            return nullptr;
        }
        if (ObjectIndex < 0)
        {
            return nullptr;
        }
 
        FUObjectItem* ObjectItem = GUObjectArray.IndexToObject(ObjectIndex);
        bool bResolved = false;
        // if an existing object is marked as Remote it needs to be resolved before its ObjectItem is returned
        if (!ObjectItem || ObjectItem->HasAnyFlags(EInternalObjectFlags::Remote))
        {
            ObjectItem = TryResolveRemoteObject();
            if (!ObjectItem)
            {
                return nullptr;
            }
            bResolved = true;
        }
        // TryResolveRemoteObject already validated the serial number
        if (!bResolved && !SerialNumbersMatch(ObjectItem))
        {
            ObjectItem = TryResolveRemoteObject();
            if (!ObjectItem)
            {
                return nullptr;
            }
        }
        return ObjectItem;
#else
        if (ObjectSerialNumber == 0)
        {
#if UE_WEAKOBJECTPTR_ZEROINIT_FIX
            checkSlow(ObjectIndex == InvalidWeakObjectIndex); // otherwise this is a corrupted weak pointer
#else
            checkSlow(ObjectIndex == 0 || ObjectIndex == -1); // otherwise this is a corrupted weak pointer
#endif
 
            return nullptr;
        }
 
        if (ObjectIndex < 0)
        {
            return nullptr;
        }
        FUObjectItem* const ObjectItem = GUObjectArray.IndexToObject(ObjectIndex);
        if (!ObjectItem)
        {
            return nullptr;
        }
        if (!SerialNumbersMatch(ObjectItem))
        {
            return nullptr;
        }
        return ObjectItem;
#endif // UE_WITH_REMOTE_OBJECT_HANDLE
    }
 
#if UE_WITH_REMOTE_OBJECT_HANDLE
    inline bool Internal_IsValid(bool bEvenIfGarbage, bool bThreadsafeTest) const
    {
        using namespace UE::Core::Private;
 
        if (IsExplicitlyNull())
        {
            return false;
        }
        if (ObjectIndex < 0)
        {
            return false;
        }
 
        FUObjectItem* ObjectItem = GUObjectArray.IndexToObject(ObjectIndex);
        if (!ObjectItem || !SerialNumbersMatch(ObjectItem))
        {
            return CanBeResolved();
        }
        else if (bThreadsafeTest)
        {
            return true;
        }
        return GUObjectArray.IsValid(ObjectItem, bEvenIfGarbage);
    }
#else
    inline bool Internal_IsValid(bool bEvenIfGarbage, bool bThreadsafeTest) const
    {
        FUObjectItem* const ObjectItem = Internal_GetObjectItem();
        if (bThreadsafeTest)
        {
            return (ObjectItem != nullptr);
        }
        else
        {
            return (ObjectItem != nullptr) && GUObjectArray.IsValid(ObjectItem, bEvenIfGarbage);
        }
    }
#endif
 
    inline UObject* Internal_Get(bool bEvenIfGarbage) const
    {
        FUObjectItem* const ObjectItem = Internal_GetObjectItem();
        return ((ObjectItem != nullptr) && GUObjectArray.IsValid(ObjectItem, bEvenIfGarbage)) ? (UObject*)ObjectItem->GetObject() : nullptr;
    }
 
    COREUOBJECT_API TStrongObjectPtr<UObject> Internal_Pin(bool bEvenIfGarbage) const;
    COREUOBJECT_API TStrongObjectPtr<UObject> Internal_TryPin(bool& bOutPinValid, bool bEvenIfGarbage) const;
    
#if UE_WEAKOBJECTPTR_ZEROINIT_FIX
    int32       ObjectIndex = UE::Core::Private::InvalidWeakObjectIndex;
    int32       ObjectSerialNumber = 0;
#else
    int32       ObjectIndex;
    int32       ObjectSerialNumber;
#endif // UE_WEAKOBJECTPTR_ZEROINIT_FIX
#if UE_WITH_REMOTE_OBJECT_HANDLE
    FRemoteObjectId ObjectRemoteId;
#endif // UE_WITH_REMOTE_OBJECT_HANDLE
 
};
 
UE_FORCEINLINE_HINT uint32 GetTypeHash(const FWeakObjectPtr& WeakObjectPtr)
{
    return WeakObjectPtr.GetTypeHash();
}