TaskSyncManager.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Engine/EngineBaseTypes.h"
#include "Misc/TransactionallySafeCriticalSection.h"
#include "Engine/DeveloperSettings.h"
#include "Async/TaskGraphFwd.h"
#include "Delegates/Delegate.h"
 
#include "TaskSyncManager.generated.h"
 
// NOTE: This header file is considered Experimental and will remain so until the release of 5.6. It will be split into multiple headers
 
namespace UE::Tick
{
 
UENUM()
enum class ESyncPointEventType : uint8
{
    Invalid,
 
    SimpleEvent,
 
    GameThreadTask,
 
    GameThreadTask_HighPriority,
 
    WorkerThreadTask,
 
    WorkerThreadTask_HighPriority,
};
 
UENUM()
enum class ESyncPointActivationRules : uint8
{
    Invalid,
 
    AlwaysActivate,
 
    WaitForTrigger,
 
    WaitForAllWork,
 
    ActivateForAnyWork,
};
 
USTRUCT()
struct FSyncPointDescription
{
    GENERATED_BODY()
 
    
    UPROPERTY(EditDefaultsOnly, Category="Task")
    FName RegisteredName;
 
    FName SourceName;
 
    UPROPERTY(EditDefaultsOnly, Category="Task")
    ESyncPointEventType EventType = ESyncPointEventType::Invalid;
 
    UPROPERTY(EditDefaultsOnly, Category="Task")
    ESyncPointActivationRules ActivationRules = ESyncPointActivationRules::Invalid;
 
    UPROPERTY(EditDefaultsOnly, Category="Task")
    TEnumAsByte<enum ETickingGroup> FirstPossibleTickGroup = TG_PrePhysics;
 
    UPROPERTY(EditDefaultsOnly, Category="Task")
    TEnumAsByte<enum ETickingGroup> LastPossibleTickGroup = TG_LastDemotable;
 
    UPROPERTY(EditDefaultsOnly, Category="Task")
    TArray<FName> PrerequisiteSyncGroups;
 
    inline bool IsValid() const
    {
        return !RegisteredName.IsNone();
    }
 
    inline bool WasLoadedFromSettings() const 
    {
        return SourceName.IsNone();
    }
};
 
UCLASS(config = Engine, defaultconfig, meta = (DisplayName = "Task Synchronization"), MinimalAPI)
class UTaskSyncManagerSettings : public UDeveloperSettings
{
    GENERATED_BODY()
 
#if WITH_EDITOR
    virtual void PostEditChangeProperty(FPropertyChangedEvent& PropertyChangedEvent) override;
    virtual bool SupportsAutoRegistration() const override;
#endif
 
public:
    UPROPERTY(config, EditAnywhere, Category = "Task Synchronization")
    TArray<FSyncPointDescription> RegisteredSyncPoints;
};
 
typedef TUniqueFunction<void()> FWorkFunction;
 
enum class ESyncOperationResult : uint8
{
    Invalid,
 
    Success,
 
    // Error conditions TODO some of these are redundant
 
    SyncPointInvalid,
    SyncPointNotRegistered,
    SyncPointNotFound,
    SyncPointDisabled,
    
    SyncPointStatusIncorrect,
    EventTypeIncorrect,
    ActivationRulesIncorrect,
 
    BatchNotFound,
    WorldNotFound,
    ThreadIncorrect,
};
 
enum class ESyncPointStatus : uint8
{
    Unknown,
 
    TaskNotRegistered,
    TaskNotCreated,
    TaskCreated,
 
    DispatchWaitingForTrigger,
    DispatchWaitingForWork,
    
    Dispatched,
    Executing,
    WaitingForMoreWork,
    WaitingForManualTask,
    ExecutionComplete,
};
 
struct FTaskSyncResult
{
    ESyncOperationResult OperationResult;
    ESyncPointStatus SyncStatus;
 
    FTaskSyncResult()
        : OperationResult(ESyncOperationResult::Invalid)
        , SyncStatus(ESyncPointStatus::Unknown)
    {}
 
    FTaskSyncResult(ESyncOperationResult Result, ESyncPointStatus Status = ESyncPointStatus::Unknown)
        : OperationResult(Result)
        , SyncStatus(Status)
    {}
 
    inline bool IsValid() const
    {
        return OperationResult != ESyncOperationResult::Invalid;
    }
 
    inline bool WasSuccessful() const
    {
        return OperationResult == ESyncOperationResult::Success;
    }
 
    inline operator bool() const
    {
        return WasSuccessful();
    }
 
    inline bool WasTaskCreatedForFrame() const
    {
        return SyncStatus >= ESyncPointStatus::TaskCreated;
    }
 
    inline bool WasActivatedForFrame() const 
    {
        return SyncStatus >= ESyncPointStatus::Dispatched;
    }
};
 
 
struct FWorldContextId final
{
    // TODO Consider moving this concept into World.h
    typedef int32 FInternalId;
 
    static constexpr FInternalId InvalidWorldContextId = -1;
 
    static constexpr FInternalId DefaultWorldContextId = 0;
 
    static ENGINE_API FWorldContextId GetContextIdForWorld(const UWorld* World);
 
    FWorldContextId()
        : WorldId(InvalidWorldContextId)
    {}
 
    explicit FWorldContextId(FInternalId InWorldId)
        : WorldId(InWorldId)
    {}
 
    FWorldContextId(const UWorld* InWorld)
    {
        WorldId = GetContextIdForWorld(InWorld).WorldId;
    }
 
    inline bool IsValid() const
    {
        return WorldId > InvalidWorldContextId;
    }
 
    inline bool operator==(const FWorldContextId& Other) const
    {
        return WorldId == Other.WorldId;
    }
 
    inline bool operator!=(const FWorldContextId& Other) const
    {
        return !(*this == Other);
    }
 
    friend inline uint32 GetTypeHash(const FWorldContextId& Context)
    {
        return static_cast<uint32>(Context.WorldId);
    }
 
    FInternalId WorldId;
};
 
struct FBatchContextId final
{
    // Internal type is sometimes used as an array index
    typedef int32 FInternalId;
 
    static constexpr FInternalId InvalidBatch = -1;
 
    FBatchContextId()
        : BatchId(InvalidBatch)
    {}
 
    explicit FBatchContextId(FInternalId InBatchId)
        : BatchId(InBatchId)
    {}
 
    inline bool IsValid() const
    {
        return BatchId > InvalidBatch;
    }
 
    inline bool operator==(const FBatchContextId& Other) const
    {
        return BatchId == Other.BatchId;
    }
 
    inline bool operator!=(const FBatchContextId& Other) const
    {
        return !(*this == Other);
    }
 
    friend inline uint32 GetTypeHash(const FBatchContextId& Context)
    {
        return static_cast<uint32>(Context.BatchId);
    }
 
    FInternalId BatchId;
};
 
struct FSyncPointId final
{
    // Internal type is sometimes used as an array index
    typedef int32 FInternalId;
 
    static constexpr FInternalId InvalidSyncPoint = -1;
 
    FSyncPointId()
        : SyncId(InvalidSyncPoint)
    {}
 
    explicit FSyncPointId(FInternalId InSyncId, FBatchContextId InBatchContext)
        : SyncId(InSyncId)
        , BatchContext(InBatchContext)
    {}
 
    inline bool IsValid() const
    {
        return SyncId > InvalidSyncPoint;
    }
 
    inline FBatchContextId GetBatchContext() const
    {
        return BatchContext;
    }
 
    inline bool operator==(const FSyncPointId& Other) const
    {
        return BatchContext == Other.BatchContext && SyncId == Other.SyncId;
    }
 
    inline bool operator!=(const FSyncPointId& Other) const
    {
        return !(*this == Other);
    }
 
    friend inline uint32 GetTypeHash(const FSyncPointId& SyncPoint)
    {
        return GetTypeHash(SyncPoint.BatchContext) + SyncPoint.SyncId;
    }
 
    FInternalId SyncId;
    FBatchContextId BatchContext;
};
 
enum class ESyncWorkRepetition : uint8
{
    Never,
 
    Once,
 
    EveryFrame,
};
 
struct FActiveSyncWorkHandle final
{
    FActiveSyncWorkHandle() = default;
    ENGINE_API ~FActiveSyncWorkHandle();
 
    FActiveSyncWorkHandle(FActiveSyncWorkHandle&&) = default;
    FActiveSyncWorkHandle& operator=(FActiveSyncWorkHandle&&) = default;
 
    // These handles can be moved but not copied
    FActiveSyncWorkHandle(const FActiveSyncWorkHandle&) = delete;
    FActiveSyncWorkHandle& operator=(const FActiveSyncWorkHandle&) = delete;
 
    ENGINE_API bool IsValid() const;
 
    ENGINE_API FTickFunction* GetDependencyTickFunction();
 
    ENGINE_API bool HasReservedWork() const;
 
    ENGINE_API bool HasRequestedWork() const;
 
    ENGINE_API bool HasWorkQueue() const;
 
    ENGINE_API bool ReserveFutureWork(ESyncWorkRepetition Repeat);
 
    ENGINE_API bool RequestWork(FTickFunction* FunctionToExecute, ESyncWorkRepetition Repeat);
 
    ENGINE_API bool QueueWorkFunction(FWorkFunction&& WorkFunction);
 
    ENGINE_API bool SendQueuedWork(FGraphEventRef* TaskToExtend = nullptr);
 
    ENGINE_API bool AbandonWork();
 
    ENGINE_API bool Reset();
 
private:
    TSharedPtr<struct FActiveSyncPoint> SyncPoint;
 
    uint32 WorkIndex : 24 = 0;
 
    static constexpr uint32 MaxWorkIndex = (2 << 24) - 1;
 
    uint32 bWorkReserved : 1 = 0;
 
    uint32 bWorkRequested : 1 = 0;
 
    uint32 bHasWorkQueue : 1 = 0;
 
    inline int32 GetIndex() const
    {
        return static_cast<int32>(WorkIndex);
    }
 
    inline void ResetInternal()
    {
        SyncPoint.Reset();
        WorkIndex = 0;
        bWorkReserved = false;
        bWorkRequested = false;
        bHasWorkQueue = false;
    }
 
    friend struct FActiveSyncPoint;
    friend class FTaskSyncManager;
};
 
struct FWorkQueueTickFunction : public FTickFunction
{
    ENGINE_API FWorkQueueTickFunction();
    ENGINE_API virtual ~FWorkQueueTickFunction();
 
    inline bool IsWorkExecuting() const
    {
        return WorkExecutionIndex != INDEX_NONE;
    }
 
    inline bool HasQueuedWork() const
    {
        return IsWorkExecuting() || QueuedWork.Num() > 0;
    }
 
    inline bool IsQueueOpen() const
    {
        return !IsWorkExecuting() && bSetAsOpen;
    }
 
    ENGINE_API void SetQueueOpen(bool bShouldBeOpen);
 
    ENGINE_API bool AddWork(FWorkFunction&& Work);
 
    ENGINE_API void ClearWork();
 
    ENGINE_API void ExecuteWork();
 
    ENGINE_API void SetDebugName(FName InDebugName, const FString& InDetailString = FString());
 
    ENGINE_API void SetClearAfterExecute(bool bShouldClear);
 
    ENGINE_API void SetOpenAfterExecute(bool bShouldOpen);
 
protected:
 
    // FTickFunction interface
    ENGINE_API void ExecuteTick(float DeltaTime, ELevelTick TickType, ENamedThreads::Type CurrentThread, const FGraphEventRef& MyCompletionGraphEvent) override;
    ENGINE_API FString DiagnosticMessage() override;
    ENGINE_API FName DiagnosticContext(bool bDetailed) override;
 
    bool bSetAsOpen;
    bool bClearAfterExecute;
    bool bOpenAfterExecute;
    int32 WorkExecutionIndex;
 
    FName DebugName;
    FString DebugDetailString;
 
    // Simple queue of work to execute, could be changed to a different type in the future
    TArray<FWorkFunction> QueuedWork;
};
 
 
struct FActiveSyncPoint final : public TSharedFromThis<FActiveSyncPoint, ESPMode::ThreadSafe>, private FTickFunction
{
    ENGINE_API FActiveSyncPoint();
 
    inline const FSyncPointDescription& GetDescription() const { return SyncPointDescription; }
 
    inline const FSyncPointId& GetSyncPointId() const { return SyncPointId; }
 
    inline const FWorldContextId& GetWorldContextId() const { return WorldContextId; }
 
    inline ESyncPointStatus GetFrameStatus() const { return FrameStatus; }
 
    inline bool IsTickGroupWork() const { return !SyncPointId.IsValid(); }
 
    ENGINE_API FActiveSyncWorkHandle RegisterWorkHandle();
 
    ENGINE_API bool ReserveFutureWork(FActiveSyncWorkHandle& Handle, ESyncWorkRepetition Repeat);
 
    ENGINE_API bool RequestWork(FActiveSyncWorkHandle& Handle, FTickFunction* WorkFunction, ESyncWorkRepetition Repeat);
 
    ENGINE_API bool QueueWorkFunction(FActiveSyncWorkHandle& Handle, FWorkFunction&& WorkFunction);
 
    ENGINE_API bool SendQueuedWork(FActiveSyncWorkHandle& Handle, FGraphEventRef* TaskToExtend = nullptr);
 
    ENGINE_API bool AbandonWork(FActiveSyncWorkHandle& Handle);
 
    ENGINE_API bool ResetWorkHandle(FActiveSyncWorkHandle& Handle);
 
private:
 
    struct FActiveSyncWork
    {
        union
        {
            uint32 StateValue;
 
            struct
            {
                uint32 bHasActiveHandle : 1;
 
                uint32 bWorkReserved : 1;
 
                uint32 bWorkRequested : 1;
 
                uint32 bReserveEveryFrame : 1;
 
                uint32 bRequestEveryFrame : 1;
 
                uint32 bCurrentlyExecuting : 1;
 
                uint32 bAlreadyExecuted : 1;
 
                uint32 bLateWorkRequested : 1;
 
                uint32 bIsWorkQueueFunction : 1;
 
                uint32 bAllocatedTickFunction : 1;
            };
        };
 
        FTickFunction* TickFunction;
 
        FActiveSyncWork()
            : StateValue(0)
            , TickFunction(nullptr)
        {
        }
 
        ~FActiveSyncWork()
        {
            if (bAllocatedTickFunction && TickFunction)
            {
                delete TickFunction;
            }
        }
 
        inline void SetTickFunction(FTickFunction* InTickFunction, bool bWasAllocatedInternally)
        {
            if (bAllocatedTickFunction && TickFunction)
            {
                delete TickFunction;
            }
            TickFunction = InTickFunction;
            bAllocatedTickFunction = bWasAllocatedInternally;
        }
 
        inline void Reset()
        {
            SetTickFunction(nullptr, false);
            StateValue = 0;
        }
 
        inline bool IsInitialized() const
        {
            return StateValue != 0;
        }
 
        FActiveSyncWork(const FActiveSyncWork&) = delete;
        FActiveSyncWork& operator=(const FActiveSyncWork&) = delete;
    };
 
    struct FExecutingSyncWork
    {
        int32 ActiveWorkIndex;
 
        FTickFunction* TickFunction;
 
        FExecutingSyncWork(int32 InIndex, const FActiveSyncWork& InWork)
            : ActiveWorkIndex(InIndex),
            TickFunction(InWork.TickFunction)
        {}
 
        inline bool IsValid() const
        {
            return TickFunction != nullptr;
        }
 
        inline void Invalidate()
        {
            TickFunction = nullptr;
        }
    };
 
    // FTickFunction interface
    virtual void ExecuteTick(float DeltaTime, ELevelTick TickType, ENamedThreads::Type CurrentThread, const FGraphEventRef& MyCompletionGraphEvent) override;
    virtual FString DiagnosticMessage() override;
    virtual FName DiagnosticContext(bool bDetailed) override;
    virtual bool DispatchManually() override;
 
    void ExecuteFromGameThread(float DeltaTime, ELevelTick TickType);
 
    void ResetWorkForFrame();
 
    bool HandleFirstTickGroup();
 
    bool IsReadyToProcessWork() const;
 
    bool IsTooLateToAddWork(bool bWorkReserved) const;
 
    bool GetWorkToExecute(float DeltaTime, ELevelTick TickType, ENamedThreads::Type CurrentThread, const FGraphEventRef& MyCompletionGraphEvent);
 
    void CancelRequestedWork(int32 ActiveWorkIndex, FActiveSyncWork& CurrentWork);
 
    uint32 AllocateActiveWork();
 
    void DispatchWorkTask(FGraphEventRef* TaskToExtend = nullptr);
 
    FSyncPointDescription SyncPointDescription;
    
    FSyncPointId SyncPointId;
 
    FWorldContextId WorldContextId;
 
    ESyncPointStatus FrameStatus;
 
    FGraphEventRef ReactivationEvent;
 
    mutable FTransactionallySafeCriticalSection WorkLock;
 
    TArray<FActiveSyncWork> ActiveWork;
 
    TArray<FExecutingSyncWork> ExecutingWork;
 
    friend class FTaskSyncManager;
    friend struct FActiveSyncWorkHandle;
};
 
 
class FTaskSyncManager
{
public:
    ENGINE_API FTaskSyncManager();
    ENGINE_API ~FTaskSyncManager();
    
 
    // Thread safe accessors, safe at any time
 
    static ENGINE_API FTaskSyncManager* Get();
 
    ENGINE_API FBatchContextId FindDefaultBatch(FWorldContextId WorldContext) const;
 
    ENGINE_API FSyncPointId FindSyncPoint(FBatchContextId Batch, FName RegisteredName);
 
    ENGINE_API FSyncPointId FindSyncPoint(FWorldContextId WorldContext, FName RegisteredName);
 
 
    // These functions are thread safe and can be called by worker or game threads during a tick, if the sync point is in the proper state
 
    ENGINE_API FTaskSyncResult GetTaskGraphEvent(FSyncPointId SyncPoint, FGraphEventRef& OutEventRef);
 
    ENGINE_API FTaskSyncResult TriggerSyncPoint(FSyncPointId SyncPoint);
 
    ENGINE_API FTaskSyncResult TriggerSyncPointAfterEvent(FSyncPointId SyncPoint, FGraphEventRef EventToWairFor);
 
    ENGINE_API FTaskSyncResult RegisterWorkHandle(FSyncPointId SyncPoint, FActiveSyncWorkHandle& OutWorkHandle);
 
    ENGINE_API FTaskSyncResult RegisterTickGroupWorkHandle(FWorldContextId WorldContext, ETickingGroup TickGroup, FActiveSyncWorkHandle& OutWorkHandle);
 
    ENGINE_API FGraphEventRef CreateManualTickTask(FWorldContextId WorldContext, FTickFunction* TickFunction, float DeltaTime = -1.0f, ELevelTick TickType = LEVELTICK_All);
 
 
    // Game thread-only functions, in general these will not affect the current frame
 
    ENGINE_API void ReloadRegisteredData();
 
    ENGINE_API bool GetSyncPointDescription(FName RegisteredName, FSyncPointDescription& OutDescription) const;
 
    ENGINE_API bool RegisterNewSyncPoint(const FSyncPointDescription& NewDescription);
 
    ENGINE_API bool UnregisterSyncPoint(FName RegisteredName, FName SourceName);
 
    ENGINE_API FBatchContextId CreateNewBatch(FWorldContextId WorldContext);
 
    ENGINE_API FWorldContextId GetCurrentWorldContext() const;
 
    ENGINE_API FTickFunction* GetTickFunctionForSyncPoint(FSyncPointId SyncPoint);
 
    ENGINE_API void StartFrame(const UWorld* InWorld, float InDeltaSeconds, ELevelTick InTickType);
 
    ENGINE_API void StartTickGroup(const UWorld* InWorld, ETickingGroup TickGroup, TArray<FTickFunction*>& TicksToManualDispatch);
 
    ENGINE_API void EndTickGroup(const UWorld* InWorld, ETickingGroup TickGroup);
 
    ENGINE_API void EndFrame(const UWorld* InWorld);
 
    ENGINE_API void ReleaseWorldContext(FWorldContextId WorldContext);
private:
        
    struct FTemporaryWorkRequest
    {
        FTemporaryWorkRequest(FActiveSyncPoint* InRequestingSyncPoint, int32 InRequestingHandle)
            : RequestingSyncPoint(InRequestingSyncPoint)
            , RequestingHandle(InRequestingHandle)
        {}
 
        FActiveSyncPoint* RequestingSyncPoint;
        int32 RequestingHandle;
        FActiveSyncWorkHandle WorkHandle;
    };
 
    struct FBatchData
    {
        FBatchContextId BatchContext;
 
        FWorldContextId WorldContext;
 
        TMap<FSyncPointId::FInternalId, TSharedRef<FActiveSyncPoint>> SyncPointData;
 
        TArray<TSharedPtr<FActiveSyncPoint>> TickGroupWork;
 
        TArray<FTemporaryWorkRequest> TemporaryWorkRequests;
 
        inline void Reset()
        {
            SyncPointData.Reset();
            TickGroupWork.Reset();
            TemporaryWorkRequests.Reset();
            BatchContext = FBatchContextId();
            WorldContext = FWorldContextId();
        }
    };
 
    struct FRegisteredSyncPointData
    {
        FSyncPointId::FInternalId RegisteredId = FSyncPointId::InvalidSyncPoint;
        FSyncPointDescription RegisteredPoint;
    };
 
    // Store as a simple array for fast access, there are a small number of active batches
    TArray<FBatchData> BatchList;
 
    TMap<FSyncPointId::FInternalId, FRegisteredSyncPointData> RegisteredDataMap;
    TMap<FName, FSyncPointId::FInternalId> RegisteredNameMap;
    FSyncPointId::FInternalId HighestSyncId = FSyncPointId::InvalidSyncPoint;
 
    mutable FTransactionallySafeCriticalSection ManagerLock;
 
    const UWorld* CurrentTickWorld = nullptr;
    float CurrentDeltaTime = 0.0f;
    ELevelTick CurrentTickType = LEVELTICK_All;
    ETickingGroup CurrentTickGroup = ETickingGroup::TG_MAX;
 
    inline bool IsTicking() const { return CurrentTickWorld != nullptr; }
 
    FTaskSyncResult FindActiveSyncPoint(FSyncPointId SyncPoint, TSharedPtr<FActiveSyncPoint>& OutData);
 
    bool HandleLateWorkRequest(FActiveSyncPoint* RequestedSyncPoint, int32 RequestingHandle, FTickFunction* TickFunction);
 
    void CancelTemporaryWorkRequest(FActiveSyncPoint* RequestedSyncPoint, int32 RequestingHandle);
 
    void RegisterSyncPointInternal(const FSyncPointDescription& InDescription);
    void OnWorldContextRemove(FWorldContext& InWorldContext);
    void InitializeBatchForFrame(FBatchData& BatchData, ULevel* PersistentLevel);
    FActiveSyncPoint* GetOrCreateSyncPoint(FBatchData& BatchData, FRegisteredSyncPointData& SyncData);
    FActiveSyncPoint* GetOrCreateTickGroupWork(FBatchData& BatchData, ETickingGroup TickGroup);
 
    friend FActiveSyncPoint;
};
 
} // namespace UE::Task