Future.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "CoreTypes.h"
#include "Misc/AssertionMacros.h"
#include "Templates/UnrealTemplate.h"
#include "Templates/Function.h"
#include "Misc/Timespan.h"
#include "Templates/SharedPointer.h"
#include "Misc/DateTime.h"
#include "HAL/Event.h"
#include "HAL/PooledSyncEvent.h"
#include "Misc/ScopeLock.h"
#include "Templates/Models.h"
#include <type_traits>
 
template<typename ResultType> class TFuture;
template<typename ResultType> class TSharedFuture;
template<typename ResultType> class TPromise;
 
namespace UE::Core::Private
{
    // A concept check for a type being callable
    struct CIntCallable
    {
        template <typename Type>
        auto Requires(Type& Callable, int32 Val) -> decltype(
            Callable(Val)
        );
    };
}
 
class FFutureState
{
public:
 
    FFutureState() = default;
 
    FFutureState(TUniqueFunction<void()>&& InCompletionCallback)
        : CompletionCallback(MoveTemp(InCompletionCallback))
    {
    }
 
public:
 
    bool IsComplete() const
    {
        return bComplete;
    }
 
    bool WaitFor(const FTimespan& Duration) const
    {
        if (CompletionEvent->Wait(Duration))
        {
            return true;
        }
 
        return false;
    }
 
    void SetContinuation(TUniqueFunction<void()>&& Continuation)
    {
        bool bShouldJustRun = IsComplete();
        if (!bShouldJustRun)
        {
            FScopeLock Lock(&Mutex);
            bShouldJustRun = IsComplete();
            if (!bShouldJustRun)
            {
                CompletionCallback = MoveTemp(Continuation);
            }
        }
        if (bShouldJustRun && Continuation)
        {
            Continuation();
        }
    }
 
protected:
 
    void MarkComplete()
    {
        TUniqueFunction<void()> Continuation;
        {
            FScopeLock Lock(&Mutex);
            Continuation = MoveTemp(CompletionCallback);
            bComplete = true;
        }
        CompletionEvent->Trigger();
 
        if (Continuation)
        {
            Continuation();
        }
    }
 
private:
    mutable FCriticalSection Mutex;
 
    TUniqueFunction<void()> CompletionCallback;
 
    FPooledSyncEvent CompletionEvent{ true };
 
    TAtomic<bool> bComplete{ false };
};
 
 
template<typename ResultType>
class TFutureState
    : public FFutureState
{
public:
    using MutableResultType = typename TTypeCompatibleBytes<ResultType>::MutableGetType;
    using ConstResultType   = typename TTypeCompatibleBytes<ResultType>::ConstGetType;
    using RvalueResultType  = typename TTypeCompatibleBytes<ResultType>::RvalueGetType;
 
    TFutureState()
        : FFutureState()
    { }
 
    ~TFutureState()
    {
        if (IsComplete())
        {
            Result.DestroyUnchecked();
        }
    }
 
    TFutureState(TUniqueFunction<void()>&& CompletionCallback)
        : FFutureState(MoveTemp(CompletionCallback))
    { }
 
public:
 
    MutableResultType GetResult()
    {
        while (!IsComplete())
        {
            WaitFor(FTimespan::MaxValue());
        }
 
        return Result.GetUnchecked();
    }
    ConstResultType GetResult() const
    {
        return const_cast<TFutureState*>(this)->GetResult();
    }
 
    template<typename... ArgTypes>
    void EmplaceResult(ArgTypes&&... Args)
    {
        check(!IsComplete());
        Result.EmplaceUnchecked(Forward<ArgTypes>(Args)...);
        MarkComplete();
    }
 
private:
 
    TTypeCompatibleBytes<ResultType> Result;
};
 
/* TFuture
*****************************************************************************/
 
template <typename ResultType>
class TFutureBase
{
protected:
    using StateType = TFutureState<ResultType>;
 
public:
    using MutableResultType = typename StateType::MutableResultType;
    using ConstResultType   = typename StateType::ConstResultType;
    using RvalueResultType  = typename StateType::RvalueResultType;
 
    ConstResultType Get() const
        requires (!std::is_object_v<ResultType>)
    {
        return this->GetState()->GetResult();
    }
    ConstResultType Get() const UE_LIFETIMEBOUND
        requires (std::is_object_v<ResultType>)
    {
        return this->GetState()->GetResult();
    }
 
    bool IsReady() const
    {
        return State.IsValid() ? State->IsComplete() : false;
    }
 
    bool IsValid() const
    {
        return State.IsValid();
    }
 
    void Wait() const
    {
        if (State.IsValid())
        {
            while (!WaitFor(FTimespan::MaxValue()));
        }
    }
 
    bool WaitFor(const FTimespan& Duration) const
    {
        return State.IsValid() ? State->WaitFor(Duration) : false;
    }
 
    bool WaitUntil(const FDateTime& Time) const
    {
        return WaitFor(Time - FDateTime::UtcNow());
    }
 
protected:
 
    TFutureBase() = default;
 
    TFutureBase(TSharedPtr<StateType>&& InState)
        : State(MoveTemp(InState))
    {
    }
    TFutureBase(const TSharedPtr<StateType>& InState)
        : State(InState)
    {
    }
 
    const TSharedPtr<StateType>& GetState() const
    {
        // if you hit this assertion then your future has an invalid state.
        // this happens if you have an uninitialized future or if you moved
        // it to another instance.
        check(State.IsValid());
 
        return State;
    }
 
    template<typename Func>
    auto Then(Func Continuation);
 
    template<typename Func>
    auto Next(Func Continuation);
 
    void Reset()
    {
        if (IsValid())
        {
            this->State->SetContinuation(nullptr);
            this->State.Reset();
        }
    }
 
private:
 
    TSharedPtr<StateType> State;
};
 
 
template<typename ResultType>
class TFuture final
    : public TFutureBase<ResultType>
{
    template <typename>
    friend class TPromise;
 
    template <typename>
    friend class TFutureBase;
 
    using BaseType = TFutureBase<ResultType>;
 
    using MutableResultType = typename BaseType::MutableResultType;
    using ConstResultType   = typename BaseType::ConstResultType;
    using RvalueResultType  = typename BaseType::RvalueResultType;
 
public:
 
    TFuture() = default;
 
    // Movable-only
    TFuture(TFuture&&) = default;
    TFuture(const TFuture&) = delete;
    TFuture& operator=(TFuture&&) = default;
    TFuture& operator=(const TFuture&) = delete;
    ~TFuture() = default;
 
    MutableResultType GetMutable()
        requires (!std::is_object_v<ResultType>)
    {
        return (MutableResultType)this->Get();
    }
    MutableResultType GetMutable() UE_LIFETIMEBOUND
        requires (std::is_object_v<ResultType>)
    {
        return (MutableResultType)this->Get();
    }
 
    ResultType Consume()
    {
        TFuture Local(MoveTemp(*this));
        return (RvalueResultType)Local.Get();
    }
 
    TSharedFuture<ResultType> Share()
    {
        return TSharedFuture<ResultType>(MoveTemp(*this));
    }
 
    using BaseType::Then;
 
    using BaseType::Next;
 
    using BaseType::Reset;
 
private:
    // Forward constructors
    using BaseType::TFutureBase;
};
 
 
/* TSharedFuture
*****************************************************************************/
 
template<typename ResultType>
class TSharedFuture final
    : public TFutureBase<ResultType>
{
    template <typename>
    friend class TFuture;
 
    using BaseType = TFutureBase<ResultType>;
 
    using MutableResultType = typename BaseType::MutableResultType;
    using ConstResultType   = typename BaseType::ConstResultType;
    using RvalueResultType  = typename BaseType::RvalueResultType;
 
public:
 
    TSharedFuture() = default;
 
    TSharedFuture(TFuture<ResultType>&& Future)
        : BaseType(MoveTemp(Future))
    { }
 
    ConstResultType Get() const
    {
        // This forwarding function is necessary to 'cancel' the UE_LIFETIMEBOUND of the base class, as
        // other shared futures can keep the object alive.
        return BaseType::Get();
    }
 
private:
    // Forward constructors
    using BaseType::TFutureBase;
};
 
 
/* TPromise
*****************************************************************************/
 
template<typename ResultType>
class TPromise final
{
    using StateType = TFutureState<ResultType>;
 
    // This is necessary because we can't form references to void for the parameter of Set().
    using SetType = std::conditional_t<std::is_void_v<ResultType>, int, ResultType>;
 
public:
 
    TPromise()
        : State(MakeShared<TFutureState<ResultType>>())
    {
    }
 
    TPromise(TUniqueFunction<void()>&& CompletionCallback)
        : State(MakeShared<TFutureState<ResultType>>(MoveTemp(CompletionCallback)))
    {
    }
 
    // Movable-only
    TPromise(TPromise&& Other) = default;
    TPromise(const TPromise& Other) = delete;
    TPromise& operator=(TPromise&& Other) = default;
    TPromise& operator=(const TPromise& Other) = delete;
 
    ~TPromise()
    {
        if (State.IsValid())
        {
            // if you hit this assertion then your promise never had its result
            // value set. broken promises are considered programming errors.
            check(State->IsComplete());
        }
    }
 
    TFuture<ResultType> GetFuture()
    {
        check(!bFutureRetrieved);
        bFutureRetrieved = true;
 
        return TFuture<ResultType>(this->GetState());
    }
 
    inline void SetValue(const SetType& Result)
        requires(!std::is_void_v<ResultType>)
    {
        EmplaceValue(Result);
    }
    inline void SetValue(SetType&& Result)
        requires(!std::is_void_v<ResultType> && !std::is_lvalue_reference_v<ResultType>)
    {
        EmplaceValue(MoveTemp(Result));
    }
    inline void SetValue()
        requires(std::is_void_v<ResultType>)
    {
        EmplaceValue();
    }
 
    template <typename... ArgTypes>
    void EmplaceValue(ArgTypes&&... Args)
    {
        this->GetState()->EmplaceResult(Forward<ArgTypes>(Args)...);
    }
 
protected:
    const TSharedPtr<StateType>& GetState()
    {
        // if you hit this assertion then your promise has an invalid state.
        // this happens if you move the promise to another instance.
        check(State.IsValid());
 
        return State;
    }
 
private:
    TSharedPtr<StateType> State;
 
    bool bFutureRetrieved = false;
};
 
/* TFuture::Then
*****************************************************************************/
 
namespace FutureDetail
{
    template<typename Func, typename ParamType, typename ResultType>
    inline void SetPromiseValue(TPromise<ResultType>& Promise, Func& Function, TFuture<ParamType>&& Param)
    {
        Promise.SetValue(Function(MoveTemp(Param)));
    }
    template<typename Func, typename ParamType>
    inline void SetPromiseValue(TPromise<void>& Promise, Func& Function, TFuture<ParamType>&& Param)
    {
        Function(MoveTemp(Param));
        Promise.SetValue();
    }
}
 
// Then implementation
template<typename ResultType>
template<typename Func>
auto TFutureBase<ResultType>::Then(Func Continuation) //-> TFuture<decltype(Continuation(MoveTemp(TFuture<ResultType>())))>
{
    check(IsValid());
    using ReturnValue = decltype(Continuation(MoveTemp(TFuture<ResultType>())));
 
    TPromise<ReturnValue> Promise;
    TFuture<ReturnValue> FutureResult = Promise.GetFuture();
    TUniqueFunction<void()> Callback = [PromiseCapture = MoveTemp(Promise), ContinuationCapture = MoveTemp(Continuation), StateCapture = this->State]() mutable
    {
        FutureDetail::SetPromiseValue(PromiseCapture, ContinuationCapture, TFuture<ResultType>(MoveTemp(StateCapture)));
    };
 
    // This invalidate this future.
    TSharedPtr<StateType> MovedState = MoveTemp(this->State);
    MovedState->SetContinuation(MoveTemp(Callback));
    return FutureResult;
}
 
// Next implementation
template<typename ResultType>
template<typename Func>
auto TFutureBase<ResultType>::Next(Func Continuation) //-> TFuture<decltype(Continuation(Consume()))>
{
    return this->Then([Continuation = MoveTemp(Continuation)](TFuture<ResultType> Self) mutable
    {
        if constexpr (std::is_void_v<ResultType>)
        {
            Self.Consume();
            if constexpr (TModels_V<UE::Core::Private::CIntCallable, Func>)
            {
                UE_STATIC_DEPRECATE(5.6, true, "Passing continuations to TFuture<void>::Next which take int parameters has been deprecated - please remove the parameter.");
                return Continuation(1);
            }
            else
            {
                return Continuation();
            }
        }
        else
        {
            return Continuation(Self.Consume());
        }
    });
}
 
template<typename ResultType, typename... ArgTypes>
TPromise<ResultType> MakeFulfilledPromise(ArgTypes&&... Args)
{
    TPromise<ResultType> Promise;
    Promise.EmplaceValue(Forward<ArgTypes>(Args)...);
    return Promise;
}
 
#if UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_7
#include "Templates/Requires.h"
#endif