PreloadableFile.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Containers/Array.h"
#include "Containers/Map.h"
#include "Containers/StringFwd.h"
#include "Containers/StringView.h"
#include "Containers/UnrealString.h"
#include "CoreTypes.h"
#include "HAL/CriticalSection.h"
#include "Misc/AssertionMacros.h"
#include "Serialization/Archive.h"
#include "Templates/Atomic.h"
#include "Templates/Function.h"
#include "Templates/SharedPointer.h"
#include "Templates/UniquePtr.h"
 
class FEvent;
class IAsyncReadFileHandle;
class IAsyncReadRequest;
class IFileHandle;
 
#define FPRELOADABLEFILE_TEST_ENABLED 0
 
class FPreloadableArchive : public FArchive
{
public:
    typedef TUniqueFunction<FArchive* ()> FCreateArchive;
    typedef TUniqueFunction<IAsyncReadFileHandle* ()> FCreateAsyncArchive;
 
    enum Flags
    {
        None = 0x0,
 
        // Mode (mutually exclusive)
        ModeBits = 0x1,
        PreloadHandle = 0x0,    // Asynchronously open the Lower-Level Archive, but do not read bytes from it. The Lower-Level Archive can be detached or can be accessed through Serialize.
        PreloadBytes = 0x1,     // Asynchronously open the Lower-Level Archive and read bytes from it into an In-Memory cache of the file. Serialize will read from the cached bytes if available, otherwise will read from the Lower-Level Archive.
 
        // Options (independently selectable, do not necessarily apply to all modes)
        Prime = 0x2,            // Only applicable to PreloadHandle mode. After asynchronously opening the LowerLevel archive, asychronously call Precache(0, <PrimeSize>).
    };
    enum
    {
        DefaultPrimeSize = 1024,    // The default argument for PrimeSize in IntializeAsync. How many bytes are requested in the initial PrimeSize call.
        DefaultPageSize = 64*1024   // The default size of read requests made to the LowerLevel Archive in PreloadBytes mode when reading bytes into the In-Memory cache.
    };
 
    CORE_API FPreloadableArchive(FStringView ArchiveName);
    CORE_API virtual ~FPreloadableArchive();
 
    // Initialization
    CORE_API void SetPageSize(int64 PageSize);
    CORE_API void InitializeAsync(FCreateArchive&& InCreateArchiveFunction, uint32 InFlags = Flags::None, int64 PrimeSize = DefaultPrimeSize);
    CORE_API void InitializeAsync(FCreateAsyncArchive&& InCreateAsyncArchiveFunction, uint32 InFlags = Flags::None, int64 PrimeSize = DefaultPrimeSize);
    CORE_API bool IsInitialized() const;
    CORE_API void WaitForInitialization() const;
 
    // Preloading
    CORE_API bool StartPreload();
    CORE_API void StopPreload();
    CORE_API bool IsPreloading() const;
    CORE_API bool AllocateCache();
    CORE_API void ReleaseCache();
    CORE_API bool IsCacheAllocated() const;
    CORE_API FArchive* DetachLowerLevel();
    CORE_API bool HasValidData() const;
 
    // FArchive
    CORE_API virtual void Serialize(void* V, int64 Length) final;
    CORE_API virtual void Seek(int64 InPos) final;
    CORE_API virtual int64 Tell() final;
    CORE_API virtual int64 TotalSize() final;
    CORE_API virtual bool Close() final;
    CORE_API virtual FString GetArchiveName() const final;
 
protected:
    CORE_API void InitializeInternalAsync(FCreateArchive&& InCreateArchiveFunction, FCreateAsyncArchive&& InCreateAsyncArchiveFunction, uint32 InFlags, int64 PrimeSize);
    CORE_API void InitializeInternal(FCreateArchive&& InCreateArchiveFunction, FCreateAsyncArchive&& InCreateAsyncArchiveFunction, uint32 Flags, int64 PrimeSize);
#if FPRELOADABLEFILE_TEST_ENABLED
    CORE_API void SerializeInternal(void* V, int64 Length);
#endif
    CORE_API void PausePreload();
    CORE_API void ResumePreload();
    CORE_API bool ResumePreloadNonRecursive();
    CORE_API void OnReadComplete(bool bCanceled, IAsyncReadRequest* ReadRequest);
    CORE_API void FreeRetiredRequests();
    CORE_API void SerializeSynchronously(void* V, int64 Length);
 
    FString ArchiveName;
    int64 Pos = 0;
    int64 Size = -1;
 
    FEvent* PendingAsyncComplete = nullptr;
    TAtomic<bool> bInitialized;
    TAtomic<bool> bIsPreloading;
    TAtomic<bool> bIsPreloadingPaused;
 
    uint8* CacheBytes = nullptr;
    TAtomic<int64> CacheEnd;
 
    TUniquePtr<IAsyncReadFileHandle> AsynchronousHandle;
    TUniquePtr<FArchive> SynchronousArchive;
#if FPRELOADABLEFILE_TEST_ENABLED
    TUniquePtr<FArchive> TestArchive;
#endif
    TArray<IAsyncReadRequest*> RetiredRequests;
    int64 PageSize = DefaultPageSize;
 
    FCriticalSection PreloadLock;
    bool bReadCompleteWasCalledInline = false;
    bool bIsInlineReadComplete = false;
 
    struct FSavedReadCompleteArguments
    {
    public:
        void Set(bool bInCanceled, IAsyncReadRequest* InReadRequest)
        {
            bCanceled = bInCanceled;
            ReadRequest = InReadRequest;
        }
        void Get(bool& bOutCanceled, IAsyncReadRequest*& OutReadRequest)
        {
            bOutCanceled = bCanceled;
            OutReadRequest = ReadRequest;
            ReadRequest = nullptr;
        }
    private:
        bool bCanceled = false;
        IAsyncReadRequest* ReadRequest = nullptr;
    }
    SavedReadCompleteArguments;
 
    friend class FPreloadableFileProxy;
};
 
class FPreloadableFile : public FPreloadableArchive
{
public:
    CORE_API FPreloadableFile(FStringView FileName);
 
    CORE_API void InitializeAsync(uint32 InFlags = Flags::None, int64 PrimeSize=DefaultPrimeSize);
 
    // Registration
    static CORE_API bool TryRegister(const TSharedPtr<FPreloadableFile>& PreloadableFile);
    static CORE_API FArchive* TryTakeArchive(const TCHAR* FileName);
    static CORE_API bool UnRegister(const TSharedPtr<FPreloadableFile>& PreloadableFile);
 
private:
    static TMap<FString, TSharedPtr<FPreloadableFile>> RegisteredFiles;
};
 
class FPreloadableArchiveProxy : public FArchive
{
public:
    explicit FPreloadableArchiveProxy(const TSharedPtr<FPreloadableArchive>& InArchive)
        :Archive(InArchive)
    {
        check(Archive);
    }
    virtual void Seek(int64 InPos) final
    {
        Archive->Seek(InPos);
    }
    virtual int64 Tell() final
    {
        return Archive->Tell();
    }
    virtual int64 TotalSize() final
    {
        return Archive->TotalSize();
    }
    virtual bool Close() final
    {
        return Archive->Close();
    }
    virtual void Serialize(void* V, int64 Length) final
    {
        Archive->Serialize(V, Length);
    }
    virtual FString GetArchiveName() const final
    {
        return Archive->GetArchiveName();
    }
 
private:
    TSharedPtr<FPreloadableArchive> Archive;
};