Function.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "CoreTypes.h"
#include "AutoRTFM.h"
#include "Concepts/NotCVRefTo.h"
#include "Misc/AssertionMacros.h"
#include "Misc/IntrusiveUnsetOptionalState.h"
#include "HAL/UnrealMemory.h"
#include "Templates/FunctionFwd.h" // IWYU pragma: export
#include "Templates/UnrealTypeTraits.h"
#include "Templates/Invoke.h"
#include "Templates/UnrealTemplate.h"
#include "Templates/Requires.h"
#include "Math/UnrealMathUtility.h"
#include <new> // IWYU pragma: export
#include <type_traits>
 
// Disable visualization hack for shipping or test builds.
#if defined(UE_ENABLE_TFUNCTIONREF_VISUALIZATION) && UE_ENABLE_TFUNCTIONREF_VISUALIZATION
    COMPILE_WARNING("TFunction visualization has been removed - please undefine UE_ENABLE_TFUNCTIONREF_VISUALIZATION.")
#endif
 
#if !defined(NUM_TFUNCTION_INLINE_BYTES) || NUM_TFUNCTION_INLINE_BYTES == 0
    #define TFUNCTION_USES_INLINE_STORAGE 0
#else
    #define TFUNCTION_USES_INLINE_STORAGE 1
    #define TFUNCTION_INLINE_SIZE         NUM_TFUNCTION_INLINE_BYTES
    #define TFUNCTION_INLINE_ALIGNMENT    16
#endif
 
namespace UE::Core::Private::Function
{
    template <typename T, bool bUnique, bool bOnHeap>
    struct TFunction_OwnedObject;
 
    struct FFunctionStorage;
 
    template <bool bUnique>
    struct TFunctionStorage;
 
    struct IFunction_OwnedObject
    {
        virtual void* CloneToEmptyStorage(FFunctionStorage* Storage) const = 0;
 
        virtual void* GetAddress() = 0;
 
        virtual void Destroy() = 0;
 
        virtual ~IFunction_OwnedObject() = default;
    };
 
    template <typename T, bool bUnique, bool bOnHeap>
    struct AUTORTFM_INFER TFunction_OwnedObject : public IFunction_OwnedObject
    {
        template <typename ArgType>
        explicit TFunction_OwnedObject(ArgType&& Arg)
            : Obj(Forward<ArgType>(Arg))
        {
        }
 
        virtual void* GetAddress() override
        {
            return &Obj;
        }
 
        void* CloneToEmptyStorage(FFunctionStorage* UntypedStorage) const override;
 
        virtual void Destroy() override
        {
            if constexpr (bOnHeap)
            {
                void* This = this;
                this->~TFunction_OwnedObject();
                FMemory::Free(This);
            }
            else
            {
                this->~TFunction_OwnedObject();
            }
        }
 
        ~TFunction_OwnedObject() override
        {
            // It is not necessary to define this destructor but MSVC will
            // erroneously issue warning C5046 without it.
        }
 
        T Obj;
    };
 
    template <typename T>
    FORCEINLINE bool IsBound(const T& Func)
    {
        if constexpr (std::is_pointer_v<T> || std::is_member_pointer_v<T> || TIsTFunction<T>::Value)
        {
            // Function pointers, data member pointers, member function pointers and TFunctions
            // can all be null/unbound, so test them using their boolean state.
            return !!Func;
        }
        else
        {
            // We can't tell if any other generic callable can be invoked, so just assume they can be.
            return true;
        }
    }
 
    struct AUTORTFM_INFER FFunctionStorage
    {
        constexpr static bool bCanBeNull = true;
 
        FFunctionStorage()
            : HeapAllocation(nullptr)
        {
        }
 
        FFunctionStorage(FFunctionStorage&& Other)
            : HeapAllocation(Other.HeapAllocation)
        {
            Other.HeapAllocation = nullptr;
            #if TFUNCTION_USES_INLINE_STORAGE
                FMemory::Memcpy(&InlineAllocation, &Other.InlineAllocation, sizeof(InlineAllocation));
            #endif
        }
 
        FFunctionStorage(const FFunctionStorage& Other) = delete;
        FFunctionStorage& operator=(FFunctionStorage&& Other) = delete;
        FFunctionStorage& operator=(const FFunctionStorage& Other) = delete;
 
        void BindCopy(const FFunctionStorage& Other)
        {
            Other.GetBoundObject()->CloneToEmptyStorage(this);
        }
 
        IFunction_OwnedObject* GetBoundObject() const
        {
            IFunction_OwnedObject* Result = (IFunction_OwnedObject*)HeapAllocation;
            #if TFUNCTION_USES_INLINE_STORAGE
                if (!Result)
                {
                    Result = (IFunction_OwnedObject*)&InlineAllocation;
                }
            #endif
 
            return Result;
        }
 
        void* GetPtr() const
        {
        #if TFUNCTION_USES_INLINE_STORAGE
            IFunction_OwnedObject* Owned = (IFunction_OwnedObject*)HeapAllocation;
            if (!Owned)
            {
                Owned = (IFunction_OwnedObject*)&InlineAllocation;
            }
 
            return Owned->GetAddress();
        #else
            return ((IFunction_OwnedObject*)HeapAllocation)->GetAddress();
        #endif
        }
 
        void Unbind()
        {
            IFunction_OwnedObject* Owned = GetBoundObject();
            Owned->Destroy();
        }
 
        #if TFUNCTION_USES_INLINE_STORAGE
            // Inline storage for an owned object
            alignas(TFUNCTION_INLINE_ALIGNMENT) uint8 InlineAllocation[TFUNCTION_INLINE_SIZE];
        #endif
 
        void* HeapAllocation;
    };
 
    template <bool bUnique>
    struct AUTORTFM_INFER TFunctionStorage : FFunctionStorage
    {
        TFunctionStorage() = default;
 
        TFunctionStorage(FFunctionStorage&& Other)
            : FFunctionStorage(MoveTemp(Other))
        {
        }
 
        template <typename FunctorType>
        std::decay_t<FunctorType>* Bind(FunctorType&& InFunc)
        {
            using DecayedFunctorType = std::decay_t<FunctorType>;
 
            if (!IsBound(InFunc))
            {
                return nullptr;
            }
 
#if TFUNCTION_USES_INLINE_STORAGE
            constexpr bool bOnHeap = sizeof(TFunction_OwnedObject<DecayedFunctorType, bUnique, false>) > TFUNCTION_INLINE_SIZE;
#else
            constexpr bool bOnHeap = true;
#endif
 
            using OwnedType = TFunction_OwnedObject<DecayedFunctorType, bUnique, bOnHeap>;
 
            void* NewAlloc;
#if TFUNCTION_USES_INLINE_STORAGE
            if constexpr (!bOnHeap)
            {
                NewAlloc = &InlineAllocation;
            }
            else
#endif
            {
                NewAlloc = FMemory::Malloc(sizeof(OwnedType), alignof(OwnedType));
                HeapAllocation = NewAlloc;
            }
 
            CA_ASSUME(NewAlloc);
            auto* NewOwned = ::new (NewAlloc) OwnedType(Forward<FunctorType>(InFunc));
            return &NewOwned->Obj;
        }
    };
 
    template <typename T, bool bUnique, bool bOnHeap>
    void* TFunction_OwnedObject<T, bUnique, bOnHeap>::CloneToEmptyStorage(FFunctionStorage* UntypedStorage) const
    {
        if constexpr (bUnique)
        {
            // Should never get here - copy functions are deleted for TUniqueFunction
            check(false);
            return nullptr;
        }
        else
        {
            TFunctionStorage<false>& Storage = *static_cast<TFunctionStorage<false>*>(UntypedStorage);
 
            void* NewAlloc;
#if TFUNCTION_USES_INLINE_STORAGE
            if constexpr (!bOnHeap)
            {
                NewAlloc = &Storage.InlineAllocation;
            }
            else
#endif
            {
                NewAlloc = FMemory::Malloc(sizeof(TFunction_OwnedObject), alignof(TFunction_OwnedObject));
                Storage.HeapAllocation = NewAlloc;
                CA_ASSUME(NewAlloc);
            }
 
            auto* NewOwned = ::new (NewAlloc) TFunction_OwnedObject(this->Obj);
 
            return &NewOwned->Obj;
        }
    }
 
    template <typename Functor, typename Ret, typename... ParamTypes>
    struct AUTORTFM_INFER TFunctionRefCaller
    {
        static Ret Call(void* Obj, ParamTypes&... Params)
        {
            if constexpr (std::is_void_v<Ret>)
            {
                ::Invoke(*(Functor*)Obj, Forward<ParamTypes>(Params)...);
            }
            else
            {
                return ::Invoke(*(Functor*)Obj, Forward<ParamTypes>(Params)...);
            }
        }
    };
 
#if DO_CHECK
    // Move all of the assert code out of line.
    // This takes a void* to avoid multiple template instantiations - the caller should
    // explicitly cast the Callable function pointer to void* to call this function.
    CORE_API void CheckCallable(void* Callable);
#endif
 
    template <typename StorageType, typename FuncType>
    struct TFunctionRefBase;
 
    template <typename StorageType, typename Ret, typename... ParamTypes>
    struct AUTORTFM_INFER TFunctionRefBase<StorageType, Ret (ParamTypes...)>
    {
        template <typename OtherStorageType, typename OtherFuncType>
        friend struct TFunctionRefBase;
 
        TFunctionRefBase() = default;
 
        TFunctionRefBase(TFunctionRefBase&& Other)
            : Callable(Other.Callable)
            , Storage (MoveTemp(Other.Storage))
        {
            static_assert(StorageType::bCanBeNull, "Unable to move non-nullable storage");
 
            if (Callable)
            {
                Other.Callable = nullptr;
            }
        }
 
        template <typename OtherStorage>
        TFunctionRefBase(TFunctionRefBase<OtherStorage, Ret (ParamTypes...)>&& Other)
            : Callable(Other.Callable)
            , Storage (MoveTemp(Other.Storage))
        {
            static_assert(OtherStorage::bCanBeNull, "Unable to move from non-nullable storage");
            static_assert(StorageType::bCanBeNull,  "Unable to move into non-nullable storage");
 
            if (Callable)
            {
                Other.Callable = nullptr;
            }
        }
 
        template <typename OtherStorage>
        TFunctionRefBase(const TFunctionRefBase<OtherStorage, Ret (ParamTypes...)>& Other)
            : Callable(Other.Callable)
        {
            if constexpr (OtherStorage::bCanBeNull)
            {
                static_assert(StorageType::bCanBeNull, "Unable to copy from nullable storage into non-nullable storage");
 
                if (!Callable)
                {
                    return;
                }
            }
 
            Storage.BindCopy(Other.Storage);
        }
 
        TFunctionRefBase(const TFunctionRefBase& Other)
            : Callable(Other.Callable)
        {
            if constexpr (StorageType::bCanBeNull)
            {
                if (!Callable)
                {
                    return;
                }
            }
 
            Storage.BindCopy(Other.Storage);
        }
 
        template <UE::CNotCVRefTo<TFunctionRefBase> FunctorType>
        TFunctionRefBase(FunctorType&& InFunc)
        {
            auto* Binding = Storage.Bind(Forward<FunctorType>(InFunc));
 
            if constexpr (StorageType::bCanBeNull)
            {
                if (!Binding)
                {
                    return;
                }
            }
 
            using DecayedFunctorType = typename TRemovePointer<decltype(Binding)>::Type;
 
            Callable = &TFunctionRefCaller<DecayedFunctorType, Ret, ParamTypes...>::Call;
        }
 
        TFunctionRefBase& operator=(TFunctionRefBase&&) = delete;
        TFunctionRefBase& operator=(const TFunctionRefBase&) = delete;
 
        UE_DEPRECATED(5.7, "CheckCallable should not be called - use check(Func) instead, and for a TFunctionRef there's no need to check.")
        FORCENOINLINE void CheckCallable() const
        {
            checkf(Callable, TEXT("Attempting to call an unbound TFunction!"));
        }
 
        Ret operator()(ParamTypes... Params) const
        {
#if DO_CHECK
            if constexpr (StorageType::bCanBeNull)
            {
                UE::Core::Private::Function::CheckCallable((void*)Callable);
            }
#endif
            return Callable(Storage.GetPtr(), Params...);
        }
 
        ~TFunctionRefBase()
        {
            if constexpr (StorageType::bCanBeNull)
            {
                if (!Callable)
                {
                    return;
                }
            }
            Storage.Unbind();
        }
 
        void Reset()
        {
            if (Callable)
            {
                Storage.Unbind();
                Callable = nullptr;
            }
        }
 
    protected:
        bool IsSet() const
        {
            // Normally we'd assert that bCanBeNull here because it should always be true, but we reuse this
            // function to test that a `TOptional<TFunctionRef>` with an intrusive state is unset.
 
            return !!Callable;
        }
 
    private:
        // A pointer to a function which invokes the call operator on the callable object
        Ret (*Callable)(void*, ParamTypes&...) = nullptr;
 
        StorageType Storage;
    };
 
    struct FFunctionRefStoragePolicy
    {
        constexpr static bool bCanBeNull = false;
 
        template <typename FunctorType>
        std::remove_reference_t<FunctorType>* Bind(FunctorType&& InFunc)
        {
            checkf(IsBound(InFunc), TEXT("Cannot bind a null/unbound callable to a TFunctionRef"));
 
            Ptr = (void*)&InFunc;
            return &InFunc;
        }
 
        void BindCopy(const FFunctionRefStoragePolicy& Other)
        {
            Ptr = Other.Ptr;
        }
 
        void* GetPtr() const
        {
            return Ptr;
        }
 
        void Unbind() const
        {
            // FunctionRefs don't own their binding - do nothing
        }
 
    private:
        // A pointer to the callable object
        void* Ptr = nullptr;
    };
 
    template <typename FunctorType> auto ResolveFuncPtrTypeIfPossible(FunctorType&&, int) -> decltype(+std::declval<FunctorType>());
    template <typename FunctorType> auto ResolveFuncPtrTypeIfPossible(FunctorType&&, ...) -> FunctorType&&;
 
    template <typename FunctorType>
    using TFuncPtrTypeIfPossible_T = decltype(ResolveFuncPtrTypeIfPossible(std::declval<FunctorType&&>(), 0));
}
 
template <typename Ret, typename... ParamTypes>
class AUTORTFM_INFER TFunctionRef<Ret(ParamTypes...)> final : public UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::FFunctionRefStoragePolicy, Ret(ParamTypes...)>
{
    using Super = UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::FFunctionRefStoragePolicy, Ret(ParamTypes...)>;
 
public:
    template <typename FunctorType>
        requires (!TIsTFunctionRef<std::decay_t<FunctorType>>::Value && std::is_invocable_r_v<Ret, std::decay_t<FunctorType>, ParamTypes...>)
    TFunctionRef(FunctorType&& InFunc UE_LIFETIMEBOUND)
        : Super(Forward<FunctorType>(InFunc))
    {
        // This constructor is disabled for TFunctionRef types so it isn't incorrectly selected as copy/move constructors.
 
        // Unlike TFunction and TUniqueFunction, we do not coerce the function type to a pointer here because the functionref would
        // end up pointing to the temporary pointer we created on the stack.
    }
 
    // Start - intrusive TOptional<TFunctionRef> state //
    constexpr static bool bHasIntrusiveUnsetOptionalState = true;
    using IntrusiveUnsetOptionalStateType = TFunctionRef;
 
    explicit TFunctionRef(FIntrusiveUnsetOptionalState)
    {
    }
    bool operator==(FIntrusiveUnsetOptionalState) const
    {
        return !Super::IsSet();
    }
    // End - intrusive TOptional<TFunctionRef> state //
 
    TFunctionRef(const TFunctionRef&) = default;
 
    // We delete the assignment operators because we don't want it to be confused with being related to
    // regular C++ reference assignment - i.e. calling the assignment operator of whatever the reference
    // is bound to - because that's not what TFunctionRef does, nor is it even capable of doing that.
    TFunctionRef& operator=(const TFunctionRef&) const = delete;
    ~TFunctionRef() = default;
};
 
template <typename Ret, typename... ParamTypes>
class AUTORTFM_INFER TFunction<Ret(ParamTypes...)> final : public UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::TFunctionStorage<false>, Ret(ParamTypes...)>
{
    using Super = UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::TFunctionStorage<false>, Ret(ParamTypes...)>;
 
public:
    TFunction(TYPE_OF_NULLPTR = nullptr)
    {
    }
 
    template <typename FunctorType>
        requires (!TIsTFunction<std::decay_t<FunctorType>>::Value && std::is_invocable_r_v<Ret, std::decay_t<FunctorType>, ParamTypes...>)
    TFunction(FunctorType&& InFunc)
        : Super(static_cast<UE::Core::Private::Function::TFuncPtrTypeIfPossible_T<FunctorType>>(InFunc))
    {
        // This constructor is disabled for TFunction types so it isn't incorrectly selected as copy/move constructors.
 
        // This is probably a mistake if you expect TFunction to take a copy of what
        // TFunctionRef is bound to, because that's not possible.
        //
        // If you really intended to bind a TFunction to a TFunctionRef, you can just
        // wrap it in a lambda (and thus it's clear you're just binding to a call to another
        // reference):
        //
        // TFunction<int32(float)> MyFunction = [MyFunctionRef](float F) { return MyFunctionRef(F); };
        static_assert(!TIsTFunctionRef<std::decay_t<FunctorType>>::Value, "Cannot construct a TFunction from a TFunctionRef");
    }
 
    TFunction(TFunction&&) = default;
    TFunction(const TFunction& Other) = default;
    ~TFunction() = default;
 
    TFunction& operator=(TFunction&& Other)
    {
        Swap(*this, Other);
        return *this;
    }
 
    TFunction& operator=(const TFunction& Other)
    {
        TFunction Temp = Other;
        Swap(*this, Temp);
        return *this;
    }
 
    TFunction& operator=(TYPE_OF_NULLPTR)
    {
        Super::Reset();
        return *this;
    }
 
    FORCEINLINE explicit operator bool() const
    {
        return Super::IsSet();
    }
 
    FORCEINLINE bool IsSet() const
    {
        return Super::IsSet();
    }
 
    FORCEINLINE bool operator==(TYPE_OF_NULLPTR) const
    {
        return !*this;
    }
 
    FORCEINLINE bool operator!=(TYPE_OF_NULLPTR) const
    {
        return (bool)*this;
    }
};
 
template <typename Ret, typename... ParamTypes>
class AUTORTFM_INFER TUniqueFunction<Ret(ParamTypes...)> final : public UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::TFunctionStorage<true>, Ret(ParamTypes...)>
{
    using Super = UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::TFunctionStorage<true>, Ret(ParamTypes...)>;
 
public:
    TUniqueFunction(TYPE_OF_NULLPTR = nullptr)
    {
    }
 
    template <typename FunctorType>
        requires(!TIsTUniqueFunction<std::decay_t<FunctorType>>::Value && !TIsTFunction      <std::decay_t<FunctorType>>::Value && std::is_invocable_r_v<Ret, std::decay_t<FunctorType>, ParamTypes...>)
    TUniqueFunction(FunctorType&& InFunc)
        : Super(static_cast<UE::Core::Private::Function::TFuncPtrTypeIfPossible_T<FunctorType>>(InFunc))
    {
        // This constructor is disabled for TUniqueFunction types so it isn't incorrectly selected as copy/move constructors.
 
        // This is probably a mistake if you expect TUniqueFunction to take a copy of what
        // TFunctionRef is bound to, because that's not possible.
        //
        // If you really intended to bind a TUniqueFunction to a TFunctionRef, you can just
        // wrap it in a lambda (and thus it's clear you're just binding to a call to another
        // reference):
        //
        // TUniqueFunction<int32(float)> MyFunction = [MyFunctionRef](float F) { return MyFunctionRef(F); };
        static_assert(!TIsTFunctionRef<std::decay_t<FunctorType>>::Value, "Cannot construct a TUniqueFunction from a TFunctionRef");
    }
 
    TUniqueFunction(TFunction<Ret(ParamTypes...)>&& Other)
        : Super(MoveTemp(*(UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::TFunctionStorage<false>, Ret(ParamTypes...)>*)&Other))
    {
    }
 
    TUniqueFunction(const TFunction<Ret(ParamTypes...)>& Other)
        : Super(*(const UE::Core::Private::Function::TFunctionRefBase<UE::Core::Private::Function::TFunctionStorage<false>, Ret(ParamTypes...)>*)&Other)
    {
    }
 
    TUniqueFunction& operator=(TUniqueFunction&& Other)
    {
        Swap(*this, Other);
        return *this;
    }
 
    TUniqueFunction(TUniqueFunction&&) = default;
    TUniqueFunction(const TUniqueFunction& Other) = delete;
    TUniqueFunction& operator=(const TUniqueFunction& Other) = delete;
    ~TUniqueFunction() = default;
 
    void Reset()
    {
        *this = nullptr;
    }
 
    FORCEINLINE explicit operator bool() const
    {
        return Super::IsSet();
    }
 
    FORCEINLINE bool IsSet() const
    {
        return Super::IsSet();
    }
};
 
 
#if !PLATFORM_COMPILER_HAS_GENERATED_COMPARISON_OPERATORS
template <typename FuncType>
FORCEINLINE bool operator==(TYPE_OF_NULLPTR, const TFunction<FuncType>& Func)
{
    return !Func;
}
 
template <typename FuncType>
FORCEINLINE bool operator!=(TYPE_OF_NULLPTR, const TFunction<FuncType>& Func)
{
    return (bool)Func;
}
#endif
 
#if UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_4
#include "Templates/AndOrNot.h"
#include "Templates/Decay.h"
#include "Templates/IsConstructible.h"
#include "Templates/IsInvocable.h"
#include "Templates/IsPointer.h"
#include "Templates/IsMemberPointer.h"
#include "Templates/RemoveReference.h"
#endif