EventLoopTimer.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
#pragma once
 
#include "CoreTypes.h"
#include "EventLoop/EventLoopManagedStorage.h"
#include "Templates/Function.h"
#include "Misc/ScopeExit.h"
#include "Misc/Timespan.h"
#include "Stats/Stats.h"
 
namespace UE::EventLoop {
 
struct FTimerHandleTraits
{
    static constexpr TCHAR Name[] = TEXT("TimerHandle");
};
 
using FTimerCallback = TUniqueFunction<void()>;
 
using FOnTimerCleared = FManagedStorageOnRemoveComplete;
 
using FTimerHandle = TResourceHandle<FTimerHandleTraits>;
 
enum class ETimerStatus : uint8
{
    Pending,
    Active,
    PendingRemoval,
    PendingReschedule,
    Executing,
};
 
struct FTimerData
{
    FTimerData(FTimerCallback&& InCallback, TOptional<FTimespan> InFirstDelay, FTimespan InRate, bool bInRepeat)
        : Callback(MoveTemp(InCallback))
        , FirstDelay(InFirstDelay)
        , Rate(InRate)
        , bRepeat(bInRepeat)
    {
    }
 
    FTimerCallback Callback;
 
    TOptional<FTimespan> FirstDelay;
 
    FTimespan Rate;
 
    FTimespan Expiration;
 
    ETimerStatus Status = ETimerStatus::Pending;
 
    uint8 bRepeat : 1;
 
    FTimerData() = default;
 
    // Movable only
    FTimerData(FTimerData&&) = default;
    FTimerData(const FTimerData&) = delete;
    FTimerData& operator=(FTimerData&&) = default;
    FTimerData& operator=(const FTimerData&) = delete;
};
 
struct FTimerManagerTraitsBase
{
    static inline void CheckIsManagerThread(bool bIsManagerThread)
    {
        check(bIsManagerThread);
    }
};
 
/*
 * Default traits for timer manager. Traits are used to implement functionality which can be
 * mocked to allow testing the class.
 *
 * In most cases the default traits can be used without modification.
 */
struct FTimerManagerDefaultTraits : public FTimerManagerTraitsBase
{
    using FTimerHeapAllocatorType = TInlineAllocator<32>;
 
    using FTimerRepeatAllocatorType = TInlineAllocator<32>;
 
    struct FStorageTraits : public FManagedStorageDefaultTraits
    {
        using FExternalHandle = FTimerHandle;
    };
};
 
template <typename Traits = FTimerManagerDefaultTraits>
class TTimerManager final : public FNoncopyable
{
public:
    using FStorageType = TManagedStorage<FTimerData, typename Traits::FStorageTraits>;
    using FTimerHandle = typename FStorageType::FExternalHandle;
    using FInternalHandle = typename FStorageType::FInternalHandle;
    using FInternalHandleArryType = typename FStorageType::FInternalHandleArryType;
 
public:
    void Init()
    {
        Storage.Init();
    }
 
    void Tick(FTimespan DeltaTime);
 
    inline bool GetNextTimeout(FTimespan& OutTimeout) const
    {
        if (!ActiveTimerHeap.IsEmpty())
        {
            FInternalHandle TopHandle = ActiveTimerHeap.HeapTop();
            const FTimerData* TimerData = Storage.Find(TopHandle);
            OutTimeout = TimerData->Expiration - InternalTime;
            return true;
        }
 
        return false;
    }
 
    inline uint32 GetNumTimers() const
    {
        return Storage.Num();
    }
 
    inline FTimerHandle SetTimer(FTimerCallback&& Callback, FTimespan InRate, bool InbRepeat = false, TOptional<FTimespan> InFirstDelay = TOptional<FTimespan>())
    {
        // Callback must be set.
        const bool bValidCallback = Callback.operator bool();
        // Rate cannot be less than zero.
        const bool bValidRate = InRate >= FTimespan::Zero();
        // First delay is only valid when repeating.
        const bool bFirstDelaySetValid = !InFirstDelay.IsSet() || InbRepeat;
        // First delay cannot be less than zero.
        const bool bFirstDelayValidTime = !InFirstDelay.IsSet() || (*InFirstDelay >= FTimespan::Zero());
 
        if (!(bValidCallback && bValidRate && bFirstDelaySetValid && bFirstDelayValidTime))
        {
            return FTimerHandle();
        }
 
        return Storage.Add(FTimerData(MoveTemp(Callback), InFirstDelay, InRate, InbRepeat));
    }
 
    inline void ClearTimer(FTimerHandle& InHandle, FOnTimerCleared&& OnTimerCleared = FOnTimerCleared())
    {
        // If ClearTimer is run from the manager thread and the timer manager is currently ticking,
        // mark the timer as pending removal so that it will not be run.
        if (Storage.IsManagerThread() && bIsTicking)
        {
            if (FTimerData* TimerData = Storage.Find(InHandle))
            {
                TimerData->Status = ETimerStatus::PendingRemoval;
            }
        }
 
        // Queue removal request.
        Storage.Remove(InHandle, MoveTemp(OnTimerCleared));
 
        // Invalidate the handle.
        InHandle.Invalidate();
    }
 
    inline bool HasPendingRepeatTimer() const
    {
        return !PendingRepeatTimers.IsEmpty();
    }
 
private:
    struct FTimerHeapOrder
    {
        explicit FTimerHeapOrder(const FStorageType& InStorage)
            : Storage(InStorage)
            , NumTimers(InStorage.Num())
        {
        }
 
        bool operator()(FInternalHandle LhsHandle, FInternalHandle RhsHandle) const
        {
            const FTimerData* LhsData = Storage.Find(LhsHandle);
            const FTimerData* RhsData = Storage.Find(RhsHandle);
 
            // Move to top if empty.
            if (LhsData == nullptr)
            {
                return true;
            }
 
            // Move to top if empty.
            if (RhsData == nullptr)
            {
                return false;
            }
 
            return LhsData->Expiration < RhsData->Expiration;
        }
 
        const FStorageType& Storage;
        int32 NumTimers;
    };
 
    FStorageType Storage;
    TArray<FInternalHandle, typename Traits::FTimerHeapAllocatorType> ActiveTimerHeap;
    TArray<FInternalHandle, typename Traits::FTimerRepeatAllocatorType> PendingRepeatTimers;
    FTimespan InternalTime;
    bool bIsTicking = false;
};
 
template <typename Traits>
void TTimerManager<Traits>::Tick(FTimespan DeltaTime)
{
    QUICK_SCOPE_CYCLE_COUNTER(STAT_EventLoop_TTimerManager_Tick);
 
    Traits::CheckIsManagerThread(Storage.IsManagerThread());
 
    bIsTicking = true;
    ON_SCOPE_EXIT{ bIsTicking = false; };
 
    // Progress internal time.
    InternalTime += DeltaTime;
 
    // Process queued actions.
    FInternalHandleArryType AddedHandles;
    FInternalHandleArryType RemovedHandles;
    Storage.Update(&AddedHandles, &RemovedHandles);
 
    {
        QUICK_SCOPE_CYCLE_COUNTER(STAT_EventLoop_TTimerManager_Tick_AddTimers);
 
        // Activate new timers.
        // Timers are always added on the next call to Tick regardless of thread to provide the
        // guarantee that a timer may fire late, but never early.
        for (FInternalHandle InternalHandle : AddedHandles)
        {
            // Timer data may not be found if the timer was added and removed before Tick was called.
            if (FTimerData* TimerData = Storage.Find(InternalHandle))
            {
                const FTimespan EffectiveInitialRate = TimerData->FirstDelay ? *TimerData->FirstDelay : TimerData->Rate;
                TimerData->Expiration = InternalTime + EffectiveInitialRate;
                TimerData->Status = ETimerStatus::Active;
                ActiveTimerHeap.HeapPush(InternalHandle, FTimerHeapOrder(Storage));
            }
        }
    }
 
    {
        QUICK_SCOPE_CYCLE_COUNTER(STAT_EventLoop_TTimerManager_Tick_RemoveTimers);
 
        // Clear removed timers.
        for (FInternalHandle InternalHandle : RemovedHandles)
        {
            // Index may not be found if the timer was added and removed before Tick was called.
            int32 InternalHandleIndex = ActiveTimerHeap.Find(InternalHandle);
            if (InternalHandleIndex != INDEX_NONE)
            {
                ActiveTimerHeap.HeapRemoveAt(InternalHandleIndex, FTimerHeapOrder(Storage), EAllowShrinking::No);
            }
        }
    }
 
    {
        QUICK_SCOPE_CYCLE_COUNTER(STAT_EventLoop_TTimerManager_Tick_RescheduleTimers);
 
        // Schedule timers waiting to be repeated.
        for (FInternalHandle InternalHandle : PendingRepeatTimers)
        {
            // Index may not be found if the timer was removed before Tick was called.
            if (FTimerData* TimerData = Storage.Find(InternalHandle))
            {
                TimerData->Expiration = InternalTime + TimerData->Rate;
                TimerData->Status = ETimerStatus::Active;
                ActiveTimerHeap.HeapPush(InternalHandle, FTimerHeapOrder(Storage));
            }
        }
        PendingRepeatTimers.Empty();
    }
 
    {
        QUICK_SCOPE_CYCLE_COUNTER(STAT_EventLoop_TTimerManager_Tick_RunTimers);
 
        while (ActiveTimerHeap.Num() > 0)
        {
            FInternalHandle TopHandle = ActiveTimerHeap.HeapTop();
            FTimerData* TimerData = Storage.Find(TopHandle);
 
            // TimerHeap is now resolved with Storage. All entries are valid.
            check(TimerData);
 
            // Pop from heap and continue if timer was removed during iteration.
            // The timer data will be removed on the next call to Update.
            if (TimerData->Status == ETimerStatus::PendingRemoval)
            {
                FInternalHandle TimerHandle;
                ActiveTimerHeap.HeapPop(TimerHandle, FTimerHeapOrder(Storage), EAllowShrinking::No);
                continue;
            }
 
            if (InternalTime >= TimerData->Expiration)
            {
                FInternalHandle TimerHandle;
                ActiveTimerHeap.HeapPop(TimerHandle, FTimerHeapOrder(Storage), EAllowShrinking::No);
 
                // Fire user timer callback.
                TimerData->Status = ETimerStatus::Executing;
                TimerData->Callback();
 
                // Reschedule repeating timers.
                if (TimerData->bRepeat)
                {
                    TimerData->Status = ETimerStatus::PendingReschedule;
                    PendingRepeatTimers.Add(TimerHandle);
                }
                else
                {
                    // Timer has been fired and is non-repeating. Remove the timer.
                    Storage.Remove(TopHandle);
                }
            }
            else
            {
                break;
            }
        }
    }
}
 
/* UE::EventLoop */ }