AsyncFileHandle.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/Function.h"
#include "Stats/Stats.h"
#include "GenericPlatform/GenericPlatformFile.h"
#include "Templates/Function.h"
 
class IAsyncReadRequest;
 
DECLARE_MEMORY_STAT_EXTERN(TEXT("Async File Handle Memory"), STAT_AsyncFileMemory, STATGROUP_Memory, CORE_API);
DECLARE_DWORD_ACCUMULATOR_STAT_EXTERN(TEXT("Num Async File Handles"), STAT_AsyncFileHandles, STATGROUP_Memory, CORE_API);
DECLARE_DWORD_ACCUMULATOR_STAT_EXTERN(TEXT("Num Async File Requests"), STAT_AsyncFileRequests, STATGROUP_Memory, CORE_API);
 
// Note on threading. Like the rest of the filesystem platform abstraction, these methods are threadsafe, but it is expected you are not concurrently _using_ these data structures. 
 
class IAsyncReadRequest;
typedef TFunction<void(bool bWasCancelled, IAsyncReadRequest*)> FAsyncFileCallBack;
 
// Hacky base class to avoid 8 bytes of padding after the vtable
class IAsyncReadRequestFixLayout
{
public:
    virtual ~IAsyncReadRequestFixLayout() = default;
};
 
class IAsyncReadRequest : public IAsyncReadRequestFixLayout
{
protected:
    union
    {
        PTRINT Size;
        uint8* Memory;
    };
    FAsyncFileCallBack Callback;
    TSAN_ATOMIC(bool) bDataIsReady;
    TSAN_ATOMIC(bool) bCompleteAndCallbackCalled;
    TSAN_ATOMIC(bool) bCompleteSync;
    TSAN_ATOMIC(bool) bCanceled;
    const bool bSizeRequest;
    const bool bUserSuppliedMemory;
public:
 
    inline IAsyncReadRequest(FAsyncFileCallBack* InCallback, bool bInSizeRequest, uint8* UserSuppliedMemory)
        : bDataIsReady(false)
        , bCompleteAndCallbackCalled(false)
        , bCompleteSync(false)
        , bCanceled(false)
        , bSizeRequest(bInSizeRequest)
        , bUserSuppliedMemory(!!UserSuppliedMemory)
    {
        if (InCallback)
        {
            Callback = *InCallback;
        }
        if (bSizeRequest)
        {
            Size = -1;
            check(!UserSuppliedMemory && !bUserSuppliedMemory); // size requests don't do memory
        }
        else
        {
            Memory = UserSuppliedMemory;
            check((!!Memory) == bUserSuppliedMemory);
        }
        INC_DWORD_STAT(STAT_AsyncFileRequests);
    }
 
    /* Not legal to destroy the request until it is complete. */
    virtual ~IAsyncReadRequest()
    {
        // check(bCompleteAndCallbackCalled && (bSizeRequest || !Memory)); // must be complete, and if it was a read request, the memory should be gone
        UE_CLOG(!(bCompleteAndCallbackCalled && (bSizeRequest || !Memory)),
            LogHAL, Fatal, TEXT("IAsyncReadRequests must not be deleted until they are completed.")
        );
        DEC_DWORD_STAT(STAT_AsyncFileRequests);
    }
 
    UE_FORCEINLINE_HINT bool PollCompletion()
    {
        return bCompleteAndCallbackCalled;
    }
 
    inline bool WaitCompletion(float TimeLimitSeconds = 0.0f)
    {
        if (PollCompletion())
        {
            return true;
        }
        WaitCompletionImpl(TimeLimitSeconds);
        return PollCompletion();
    }
 
    virtual void EnsureCompletion()
    {
        // Default implementation is the same as WaitCompletion(0.0f) except that it skips the testing of
        // PollCompletion. This is potentially slower because we do not early exit if PollCompletion is true, but it
        // provides a stronger guarantee of completion because PollCompletion can sometimes return true while
        // completion steps are still in progress.
        WaitCompletionImpl(0.0f);
    }
 
    inline void Cancel()
    {
        if (!bCanceled)
        {
            bCanceled = true;
            bDataIsReady = true;
            FPlatformMisc::MemoryBarrier();
            if (!PollCompletion())
            {
                return CancelImpl();
            }
        }
    }
 
    inline int64 GetSizeResults()
    {
        check(bDataIsReady && bSizeRequest);
        return bCanceled ? -1 : Size;
    }
 
    inline uint8* GetReadResults()
    {
        check(bDataIsReady && !bSizeRequest);
        uint8* Result = Memory;
        if (bCanceled && Result)
        {
            Result = nullptr;
        }
        else
        {
            if (Memory && !bUserSuppliedMemory)
            {
                ReleaseMemoryOwnershipImpl();
            }
 
            Memory = nullptr;
        }
        return Result;
    }
 
protected:
    virtual void WaitCompletionImpl(float TimeLimitSeconds) = 0;
 
    virtual void CancelImpl() = 0;
 
    virtual void ReleaseMemoryOwnershipImpl() = 0;
 
    void SetDataComplete()
    {
        bDataIsReady = true;
        FPlatformMisc::MemoryBarrier();
        if (Callback)
        {
            Callback(bCanceled, this);
        }
        FPlatformMisc::MemoryBarrier();
    }
 
    void SetAllComplete()
    {
        bCompleteAndCallbackCalled = true;
        FPlatformMisc::MemoryBarrier();
    }
 
    void SetComplete()
    {
        SetDataComplete();
        SetAllComplete();
    }
};
 
class IAsyncReadFileHandle
{
public:
    IAsyncReadFileHandle()
    {
        INC_DWORD_STAT(STAT_AsyncFileHandles);
    }
    virtual ~IAsyncReadFileHandle()
    {
        DEC_DWORD_STAT(STAT_AsyncFileHandles);
    }
 
    virtual IAsyncReadRequest* SizeRequest(FAsyncFileCallBack* CompleteCallback = nullptr) = 0;
 
    virtual IAsyncReadRequest* ReadRequest(int64 Offset, int64 BytesToRead, EAsyncIOPriorityAndFlags PriorityAndFlags = AIOP_Normal, FAsyncFileCallBack* CompleteCallback = nullptr, uint8* UserSuppliedMemory = nullptr) = 0;
 
    virtual bool UsesCache()
    {
        return true;
    }
 
    virtual void ShrinkHandleBuffers()
    { }
 
    // Non-copyable
    IAsyncReadFileHandle(const IAsyncReadFileHandle&) = delete;
    IAsyncReadFileHandle& operator=(const IAsyncReadFileHandle&) = delete;
};