BulkData.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Async/AsyncFileHandle.h"
#include "BulkDataBuffer.h"
#include "Containers/Array.h"
#include "Containers/ContainerAllocationPolicies.h"
#include "Containers/Map.h"
#include "Containers/SortedMap.h"
#include "Containers/StringView.h"
#include "Containers/StringFwd.h"
#include "Containers/UnrealString.h"
#include "CoreMinimal.h"
#include "CoreTypes.h"
#include "GenericPlatform/GenericPlatformFile.h"
#include "HAL/MemoryBase.h"
#include "IO/IoChunkId.h"
#include "IO/IoDispatcherPriority.h"
#include "IO/PackageId.h"
#include "Math/NumericLimits.h"
#include "Misc/AssertionMacros.h"
#include "Misc/CompressionFlags.h"
#include "Misc/EnumClassFlags.h"
#include "Misc/OptionalFwd.h"
#include "Misc/PackagePath.h"
#include "Misc/PackageSegment.h"
#include "Serialization/Archive.h"
#include "Serialization/BulkDataCookedIndex.h"
#include "Serialization/CustomVersion.h"
#include "Serialization/FileRegions.h"
#include "Templates/Function.h"
#include "Templates/IsPODType.h"
#include "Templates/RefCounting.h"
#include "Templates/UniquePtr.h"
#include "Templates/PimplPtr.h"
#include "UObject/NameTypes.h"
 
class FIoBuffer;
class FLinkerLoad;
class FOutputDevice;
class IAsyncReadFileHandle;
class IAsyncReadRequest;
class UObject;
struct FTimespan;
struct FIoOffsetAndLength;
namespace UE { namespace Serialization { class FEditorBulkData; } }
enum class EFileRegionType : uint8;
 
#if WITH_EDITOR == 0 && WITH_EDITORONLY_DATA == 0
    #define USE_RUNTIME_BULKDATA 1
#else
    #define USE_RUNTIME_BULKDATA 0
#endif
 
// When set to 1 attempting to reload inline data will fail with the old loader in the same way that it fails in
// the new loader to keep the results consistent.
#define UE_KEEP_INLINE_RELOADING_CONSISTENT 0
 
class IMappedFileHandle;
class IMappedFileRegion;
 
/*-----------------------------------------------------------------------------
    I/O filename helper(s)
-----------------------------------------------------------------------------*/
 
using FIoFilenameHash = uint32;
inline const FIoFilenameHash INVALID_IO_FILENAME_HASH = 0;
COREUOBJECT_API FIoFilenameHash MakeIoFilenameHash(const FString& Filename);
COREUOBJECT_API FIoFilenameHash MakeIoFilenameHash(const FPackagePath& Filename);
COREUOBJECT_API FIoFilenameHash MakeIoFilenameHash(const FIoChunkId& ChunkID);
 
class IBulkDataIORequest
{
public:
    virtual ~IBulkDataIORequest() {}
 
    virtual bool PollCompletion() const = 0;
    virtual bool WaitCompletion(float TimeLimitSeconds = 0.0f) = 0;
 
    virtual uint8* GetReadResults() = 0;
    virtual int64 GetSize() const = 0;
 
    virtual void Cancel() = 0;
};
 
enum EBulkDataFlags : uint32
{
    BULKDATA_None = 0,
    BULKDATA_PayloadAtEndOfFile = 1 << 0,
    BULKDATA_SerializeCompressedZLIB = 1 << 1,
    BULKDATA_ForceSingleElementSerialization = 1 << 2,
    BULKDATA_SingleUse = 1 << 3,
    BULKDATA_Unused UE_DEPRECATED(5.3, "This feature is being removed") = 1 << 5,
    BULKDATA_ForceInlinePayload = 1 << 6,
    BULKDATA_SerializeCompressed = (BULKDATA_SerializeCompressedZLIB),
    BULKDATA_ForceStreamPayload UE_DEPRECATED(5.3, "This flag has had no purpose for sometime") = 1 << 7,
    BULKDATA_PayloadInSeparateFile = 1 << 8,
    BULKDATA_PayloadInSeperateFile UE_DEPRECATED(5.7, "This flag has been renamed to BULKDATA_PayloadInSeparateFile") = BULKDATA_PayloadInSeparateFile,
    BULKDATA_SerializeCompressedBitWindow UE_DEPRECATED(5.3, "This flag has had no purpose for sometime") = 1 << 9,
    BULKDATA_Force_NOT_InlinePayload = 1 << 10,
    BULKDATA_OptionalPayload = 1 << 11,
    BULKDATA_MemoryMappedPayload = 1 << 12,
    BULKDATA_Size64Bit = 1 << 13,
    BULKDATA_DuplicateNonOptionalPayload = 1 << 14,
    BULKDATA_BadDataVersion UE_DEPRECATED(5.3, "This flag has had no purpose for sometime") = 1 << 15,
    BULKDATA_NoOffsetFixUp = 1 << 16,
    BULKDATA_WorkspaceDomainPayload = 1 << 17,
    BULKDATA_LazyLoadable = 1 << 18,
 
    /* Runtime only flags below this point! Note that they take the high bits in reverse order! */
 
    BULKDATA_UsesIoDispatcher = 1u << 31u,
    BULKDATA_DataIsMemoryMapped = 1 << 30,
    BULKDATA_HasAsyncReadPending UE_DEPRECATED(5.5, "This flag no longer does anything")  = 1 << 29,
    BULKDATA_AlwaysAllowDiscard = 1 << 28,
};
 
COREUOBJECT_API FStringBuilderBase& LexToString(EBulkDataFlags Flags, FStringBuilderBase& Sb);
COREUOBJECT_API FString LexToString(EBulkDataFlags Flags);
 
inline FArchive& operator<<(FArchive& Ar, EBulkDataFlags& Flags)
{
    Ar << (uint32&)Flags;
    return Ar;
}
 
enum EBulkDataLockStatus
{
    LOCKSTATUS_Unlocked = 0,
    LOCKSTATUS_ReadOnlyLock = 1,
    LOCKSTATUS_ReadWriteLock = 2,
};
 
enum EBulkDataLockFlags
{
    LOCK_READ_ONLY = 1,
    LOCK_READ_WRITE = 2,
};
 
typedef TFunction<void(bool bWasCancelled, IBulkDataIORequest*)> FBulkDataIORequestCallBack;
 
struct FOwnedBulkDataPtr
{
    explicit FOwnedBulkDataPtr(void* InAllocatedData)
        : AllocatedData(InAllocatedData)
        , MappedHandle(nullptr)
        , MappedRegion(nullptr)
    {
        
    }
 
    FOwnedBulkDataPtr(IMappedFileHandle* Handle, IMappedFileRegion* Region)
        : AllocatedData(nullptr)
        , MappedHandle(Handle)
        , MappedRegion(Region)
    {
        
    }
 
    COREUOBJECT_API ~FOwnedBulkDataPtr();
    COREUOBJECT_API const void* GetPointer();
 
    IMappedFileHandle* GetMappedHandle()
    {
        return MappedHandle;
    }
    IMappedFileRegion* GetMappedRegion()
    {
        return MappedRegion;
    }
    bool IsDataMemoryMapped() const
    {
        return MappedHandle != nullptr;
    }
 
    void RelinquishOwnership()
    {
        AllocatedData = nullptr;
        MappedHandle = nullptr;
        MappedRegion = nullptr;
    }
 
private:
    // hidden
    FOwnedBulkDataPtr() {}
 
 
    // if allocated memory was used, this will be non-null
    void* AllocatedData;
    
    // if memory mapped IO was used, these will be non-null
    IMappedFileHandle* MappedHandle;
    IMappedFileRegion* MappedRegion;
};
 
namespace UE::BulkData::Private
{
 
struct FBulkMetaResource
{
    EBulkDataFlags Flags = BULKDATA_None;
 
    int64 ElementCount = -1;
 
    int64 SizeOnDisk = -1;
    
    int64 Offset = -1;
    
    EBulkDataFlags DuplicateFlags = BULKDATA_None;
    
    int64 DuplicateSizeOnDisk = -1;
 
    int64 DuplicateOffset = -1;
 
    COREUOBJECT_API friend FArchive& operator<<(FArchive& Ar, FBulkMetaResource& BulkMeta);
};
 
class FBulkMetaData
{
public:
    static constexpr int64 MaxSize = 0xFFffFFffFF;
    static constexpr int64 MaxOffset = 0xFFffFFffFE;
 
    FBulkMetaData()
    {
        SetOffset(-1);
#if !USE_RUNTIME_BULKDATA
        SetSizeOnDisk(-1);
#endif
    }
 
    explicit FBulkMetaData(EBulkDataFlags Flags)
        : FBulkMetaData()
    {
        SetFlags(Flags);
    }
 
    inline int64 GetSize() const
    {
        return static_cast<int64>(ReadUInt40(Data));
    }
 
    inline void SetSize(int64 Size)
    {
        check(Size <= MaxSize);
        WriteUInt40(Data, uint64(Size));
    }
 
    int64 GetSizeOnDisk() const
    {
#if USE_RUNTIME_BULKDATA
        return GetSize();
#else
        return static_cast<int64>(*reinterpret_cast<const int64*>(&Data[16]));
#endif
    }
 
    void SetSizeOnDisk(int64 SizeOnDisk)
    {
#if !USE_RUNTIME_BULKDATA
        *reinterpret_cast<int64*>(&Data[16]) = SizeOnDisk;
#endif // !USE_RUNTIME_BULKDATA
    }
 
    inline int64 GetOffset() const
    {
        const int64 Offset = static_cast<int64>(ReadUInt40(Data + 5));
        return Offset > MaxOffset ? INDEX_NONE : Offset;
    }
 
    inline void SetOffset(int64 Offset)
    {
        check(Offset <= MaxOffset);
 
        if (Offset < 0)
        {
            Offset = MAX_int64;
        }
 
        WriteUInt40(Data + 5, uint64(Offset));
    }
 
    FIoOffsetAndLength GetOffsetAndLength() const;
 
    EBulkDataLockStatus GetLockStatus() const
    {
        return static_cast<EBulkDataLockStatus>(Data[11]);
    }
 
    void SetLockStatus(EBulkDataLockStatus Status)
    {
        Data[11] = uint8(Status);
    }
    
    EBulkDataFlags GetFlags() const
    {
        return static_cast<EBulkDataFlags>(*reinterpret_cast<const uint32*>(&Data[12]));
    }
 
    void SetFlags(EBulkDataFlags Flags)
    {
        *reinterpret_cast<uint32*>(&Data[12]) = static_cast<uint32>(Flags);
    }
 
    void AddFlags(EBulkDataFlags Flags)
    {
        *reinterpret_cast<uint32*>(&Data[12]) |= static_cast<uint32>(Flags);
    }
    
    void ClearFlags(EBulkDataFlags Flags)
    {
        *reinterpret_cast<uint32*>(&Data[12]) &= ~static_cast<uint32>(Flags);
    }
 
    inline bool HasAnyFlags(EBulkDataFlags Flags) const
    {
        return (GetFlags() & Flags) != 0;
    }
 
    inline bool HasAllFlags(EBulkDataFlags Flags) const
    {
        return (GetFlags() & Flags) == Flags;
    }
 
    COREUOBJECT_API static bool FromSerialized(FArchive& Ar, int64 ElementSize, FBulkMetaData& OutMetaData, int64& OutDuplicateOffset);
 
    static bool FromSerialized(FArchive& Ar, int64 ElementSize, FBulkMetaData& OutMetaData)
    {
        int64 DuplicateOffset = INDEX_NONE;
        return FromSerialized(Ar, ElementSize, OutMetaData, DuplicateOffset);
    }
 
private:
    static uint64 ReadUInt40(const uint8* Memory)
    {
        return static_cast<int64>(uint64(Memory[0]) | uint64(Memory[1]) << 8 | uint64(Memory[2]) << 16 | uint64(Memory[3]) << 24 | uint64(Memory[4]) << 32);
    }
 
    static void WriteUInt40(uint8* Memory, uint64 Value)
    {
        Memory[0] = uint8(Value); Memory[1] = uint8(Value >> 8); Memory[2] = uint8(Value >> 16); Memory[3] = uint8(Value >> 24); Memory[4] = uint8(Value >> 32);
    }
#if USE_RUNTIME_BULKDATA
    uint8 Data[16] = {0};
#else
    uint8 Data[24] = {0};
#endif // USE_RUNTIME_BULKDATA
};
 
} // namespace UE::BulkData::Private
 
struct FBulkDataSerializationParams
{
    UObject* Owner = nullptr;
    int32 ElementSize = 0;
    EFileRegionType RegionType;
    bool bAttemptMemoryMapping = false;
    FBulkDataCookedIndex CookedIndex;
};
 
class FBulkData
{
    // This struct represents an optional allocation.
    struct FAllocatedPtr
    {
        FAllocatedPtr() = default;
        ~FAllocatedPtr() = default;
 
        inline bool IsLoaded() const
        {
            return Allocation.RawData != nullptr; // Doesn't matter which allocation we test
        }
 
        void Free(FBulkData* Owner);
 
        void* ReallocateData(FBulkData* Owner, int64 SizeInBytes);
 
        void SetData(FBulkData* Owner, void* Buffer);
        void SetMemoryMappedData(FBulkData* Owner, IMappedFileHandle* MappedHandle, IMappedFileRegion* MappedRegion);
 
        void* GetAllocationForWrite(const FBulkData* Owner) const;
        const void* GetAllocationReadOnly(const FBulkData* Owner) const;
 
        COREUOBJECT_API FOwnedBulkDataPtr* StealFileMapping(FBulkData* Owner);
        void Swap(FBulkData* Owner, void** DstBuffer);
 
    private:
 
        union FAllocation
        {
            void* RawData;
            FOwnedBulkDataPtr* MemoryMappedData;
        };
 
        FAllocation Allocation{ nullptr };
    };
 
public:
    friend class FLinkerLoad;
    friend class FLinkerSave;
    friend class FExportArchive;
    friend class UE::Serialization::FEditorBulkData; // To allow access to AttachedAr
    friend class FBulkDataBatchRequest;
 
    using BulkDataRangeArray = TArray<FBulkData*, TInlineAllocator<8>>;
 
    static constexpr SIZE_T MaxBulkDataSize = (1ull << 40) - 1;
 
    /*-----------------------------------------------------------------------------
        Constructors and operators
    -----------------------------------------------------------------------------*/
 
    FBulkData() = default;
 
    COREUOBJECT_API FBulkData( const FBulkData& Other );
 
    COREUOBJECT_API ~FBulkData();
 
    COREUOBJECT_API FBulkData& operator=( const FBulkData& Other );
 
    /*-----------------------------------------------------------------------------
        Static functions.
    -----------------------------------------------------------------------------*/
 
    static COREUOBJECT_API void DumpBulkDataUsage( FOutputDevice& Log );
 
    /*-----------------------------------------------------------------------------
        Accessors
    -----------------------------------------------------------------------------*/
 
    COREUOBJECT_API int64 GetBulkDataSize() const;
    COREUOBJECT_API int64 GetBulkDataSizeOnDisk() const;
    COREUOBJECT_API int64 GetBulkDataOffsetInFile() const;
    COREUOBJECT_API bool IsStoredCompressedOnDisk() const;
 
    COREUOBJECT_API bool CanLoadFromDisk() const;
    
    COREUOBJECT_API bool DoesExist() const;
 
    COREUOBJECT_API FName GetDecompressionFormat() const;
 
    COREUOBJECT_API bool IsBulkDataLoaded() const;
 
    UE_DEPRECATED(5.5, "No longer provides any functionality (assume that this will always return true")
    COREUOBJECT_API bool IsAsyncLoadingComplete() const;
 
    UE_DEPRECATED(5.3, "The feature is being removed, it is assumed that all bulkdata is available for use")
    COREUOBJECT_API bool IsAvailableForUse() const;
 
    bool IsOptional() const
    {
        return (GetBulkDataFlags() & BULKDATA_OptionalPayload) != 0;
    }
 
    bool IsInlined() const
    {
        return   (GetBulkDataFlags() & BULKDATA_PayloadAtEndOfFile) == 0;
    }
 
    bool IsInSeparateFile() const
    {
        return  (GetBulkDataFlags() & BULKDATA_PayloadInSeparateFile) != 0;
    }
 
    bool IsInExternalResource() const
    {
        return IsInSeparateFile() && (GetBulkDataFlags() & BULKDATA_WorkspaceDomainPayload);
    }
 
    bool IsUsingIODispatcher() const
    {
        return (GetBulkDataFlags() & BULKDATA_UsesIoDispatcher) != 0;
    }
 
    bool IsDataMemoryMapped() const
    {
        return (GetBulkDataFlags() & BULKDATA_DataIsMemoryMapped) != 0;
    }
 
    bool IsSingleUse() const
    {
        return (GetBulkDataFlags() & BULKDATA_SingleUse) != 0;
    }
    
    bool IsDuplicateNonOptional() const
    {
        return (GetBulkDataFlags() & BULKDATA_DuplicateNonOptionalPayload) != 0;
    }
 
    COREUOBJECT_API void SetBulkDataFlags( uint32 BulkDataFlagsToSet );
 
    COREUOBJECT_API void ResetBulkDataFlags(uint32 BulkDataFlagsToSet);
 
    COREUOBJECT_API uint32 GetBulkDataFlags() const;
 
#if WITH_EDITOR
    COREUOBJECT_API void SetCookedIndex(FBulkDataCookedIndex Index);
#endif //WITH_EDITOR
    COREUOBJECT_API uint32 GetBulkDataAlignment() const;
 
    COREUOBJECT_API void ClearBulkDataFlags( uint32 BulkDataFlagsToClear );
 
    FIoFilenameHash GetIoFilenameHash() const { return MakeIoFilenameHash(BulkChunkId); }
    
    COREUOBJECT_API FIoChunkId CreateChunkId() const;
 
    COREUOBJECT_API FString GetDebugName() const;
 
    /*-----------------------------------------------------------------------------
        Data retrieval and manipulation.
    -----------------------------------------------------------------------------*/
 
    COREUOBJECT_API void GetCopy( void** Dest, bool bDiscardInternalCopy = true );
 
    COREUOBJECT_API void* Lock( uint32 LockFlags );
 
    COREUOBJECT_API const void* LockReadOnly() const;
 
    COREUOBJECT_API void* Realloc(int64 ElementCount, int64 ElementSize);
 
    COREUOBJECT_API void Unlock() const;
 
    bool IsLocked() const { return BulkMeta.GetLockStatus() != LOCKSTATUS_Unlocked; }
    
    bool IsUnlocked() const { return BulkMeta.GetLockStatus() == LOCKSTATUS_Unlocked; }
 
    COREUOBJECT_API void RemoveBulkData();
 
#if !USE_RUNTIME_BULKDATA
    COREUOBJECT_API bool LoadBulkDataWithFileReader();
 
    COREUOBJECT_API bool CanLoadBulkDataWithFileReader() const;
#endif // USE_RUNTIME_BULKDATA
 
    COREUOBJECT_API void ForceBulkDataResident();
    
    COREUOBJECT_API void StoreCompressedOnDisk( FName CompressionFormat );
 
    COREUOBJECT_API bool UnloadBulkData();
 
    /*-----------------------------------------------------------------------------
        Serialization.
    -----------------------------------------------------------------------------*/
 
    using FSerializeBulkDataElements = TFunction<void(FArchive&, void*, int64, EBulkDataFlags)>;
    
    COREUOBJECT_API void Serialize(FArchive& Ar, UObject* Owner, bool bAttemptFileMapping, int32 ElementSize, EFileRegionType FileRegionType);
    
    void SerializeBulkData(FArchive& Ar, void* Data, EBulkDataFlags InBulkDataFlags)
    {
        SerializeBulkData(Ar, Data, GetBulkDataSize(), InBulkDataFlags);
    }
 
    FOwnedBulkDataPtr* StealFileMapping()
    {
        // @todo if non-mapped bulk data, do we need to detach this, or mimic GetCopy more than we do?
        return DataAllocation.StealFileMapping(this); 
    }
 
    COREUOBJECT_API void GetBulkDataVersions(FArchive& InlineArchive, FPackageFileVersion& OutUEVersion, int32& OutLicenseeUEVersion,
        FCustomVersionContainer& OutCustomVersions) const;
 
#if WITH_EDITOR
    COREUOBJECT_API void SetFlagsFromDiskWrittenValues(EBulkDataFlags InBulkDataFlags, int64 InBulkDataOffsetInFile, int64 InBulkDataSizeOnDisk, int64 LinkerSummaryBulkDataStartOffset);
#endif
 
    /*-----------------------------------------------------------------------------
        Async Streaming Interface.
    -----------------------------------------------------------------------------*/
 
    COREUOBJECT_API IAsyncReadFileHandle* OpenAsyncReadHandle() const;
 
    COREUOBJECT_API IBulkDataIORequest* CreateStreamingRequest(EAsyncIOPriorityAndFlags Priority, FBulkDataIORequestCallBack* CompleteCallback, uint8* UserSuppliedMemory) const;
 
    COREUOBJECT_API IBulkDataIORequest* CreateStreamingRequest(int64 OffsetInBulkData, int64 BytesToRead, EAsyncIOPriorityAndFlags Priority, FBulkDataIORequestCallBack* CompleteCallback, uint8* UserSuppliedMemory) const;
 
    static COREUOBJECT_API void SetBulkDataFlagsOn(EBulkDataFlags& InOutAccumulator, EBulkDataFlags FlagsToSet);
    static COREUOBJECT_API void ClearBulkDataFlagsOn(EBulkDataFlags& InOutAccumulator, EBulkDataFlags FlagsToClear);
    static COREUOBJECT_API bool HasFlags(EBulkDataFlags Flags, EBulkDataFlags Contains);
    static COREUOBJECT_API FName GetDecompressionFormat(EBulkDataFlags InFlags);
 
    /*-----------------------------------------------------------------------------
        Class specific virtuals.
    -----------------------------------------------------------------------------*/
 
protected:
 
    COREUOBJECT_API void SerializeBulkData(FArchive& Ar, void* Data, int64 DataSize, EBulkDataFlags InBulkDataFlags);
 
private:
 
    COREUOBJECT_API int64 SerializePayload(FArchive& Ar, EBulkDataFlags SerializationFlags, const TOptional<EFileRegionType>& RegionType);
#if WITH_EDITOR
    COREUOBJECT_API void DetachFromArchive( FArchive* Ar, bool bEnsureBulkDataIsLoaded );
#endif // WITH_EDITOR
 
    /*-----------------------------------------------------------------------------
        Internal helpers
    -----------------------------------------------------------------------------*/
 
    COREUOBJECT_API void MakeSureBulkDataIsLoaded();
 
    COREUOBJECT_API bool TryLoadDataIntoMemory(FIoBuffer Dest);
 
    UE_DEPRECATED(5.5, "No longer provides any functionality")
    void FlushAsyncLoading() {}
 
    COREUOBJECT_API bool NeedsOffsetFixup() const;
    
    COREUOBJECT_API bool CanDiscardInternalData() const;
    
    inline void* ReallocateData(int64 SizeInBytes) { return DataAllocation.ReallocateData(this, SizeInBytes); }
 
    inline void  FreeData() { DataAllocation.Free(this); }
 
    inline void* GetDataBufferForWrite() const { return DataAllocation.GetAllocationForWrite(this); }
 
    inline const void* GetDataBufferReadOnly() const { return DataAllocation.GetAllocationReadOnly(this); }
 
    /*-----------------------------------------------------------------------------
        Member variables.
    -----------------------------------------------------------------------------*/
    
    FAllocatedPtr                           DataAllocation;
    UE::BulkData::Private::FBulkMetaData    BulkMeta;
    FIoChunkId                              BulkChunkId = FIoChunkId::InvalidChunkId;
    
protected:
#if WITH_EDITOR
    FArchive*               AttachedAr = nullptr;
    FLinkerLoad*            Linker = nullptr;
    FBulkDataCookedIndex    CookedIndex;
#endif // WITH_EDITOR
       //
#if !USE_RUNTIME_BULKDATA
    FSerializeBulkDataElements* SerializeBulkDataElements = nullptr;
#endif // !USE_RUNTIME_BULKDATA
};
 
template<typename ElementType>
class TBulkData : public FBulkData
{
public:
 
    static_assert(TIsPODType<ElementType>::Value, "Bulk data is limited to POD types");
 
    int32 GetElementSize() const
    { 
        return sizeof(ElementType);
    }
 
    int64 GetElementCount() const
    {
        return GetBulkDataSize() / sizeof(ElementType);
    }
 
    ElementType* Realloc(int64 ElementCount)
    {
        return (ElementType*)FBulkData::Realloc(ElementCount, sizeof(ElementType));
    }
 
    FBulkDataBuffer<ElementType> GetCopyAsBuffer(int64 RequestedElementCount, bool bDiscardInternalCopy)
    { 
        const int64 MaxElementCount = GetElementCount();
 
        check(RequestedElementCount <= MaxElementCount);
 
        ElementType* Ptr = nullptr;
        GetCopy((void**)& Ptr, bDiscardInternalCopy);
 
        const int64 BufferSize = (RequestedElementCount > 0 ? RequestedElementCount : MaxElementCount);
 
        return FBulkDataBuffer<ElementType>(Ptr, BufferSize);
    }
 
    void Serialize(FArchive& Ar, UObject* Owner, int32 Idx=INDEX_NONE, bool bAttemptFileMapping = false, EFileRegionType FileRegionType = EFileRegionType::None)
    {
        FBulkData::Serialize(Ar, Owner, bAttemptFileMapping, GetElementSize(), FileRegionType);
    }
 
    void SerializeWithFlags(FArchive& Ar, UObject* Owner, uint32 SaveOverrideFlags, bool bAttemptFileMapping = false, EFileRegionType FileRegionType = EFileRegionType::None)
    {
        if (Ar.IsSaving())
        {
            const uint32 OriginalBulkDataFlags = GetBulkDataFlags();
            SetBulkDataFlags(SaveOverrideFlags);        // NOTE this does an OR between existing flags and the override flags
            FBulkData::Serialize(Ar, Owner, bAttemptFileMapping, GetElementSize(), FileRegionType);
            ResetBulkDataFlags(OriginalBulkDataFlags);
        }
        else
        {
            FBulkData::Serialize(Ar, Owner, bAttemptFileMapping, GetElementSize(), FileRegionType);
        }
    }
};
 
using FByteBulkData = TBulkData<uint8>;
using FWordBulkData = TBulkData<uint16>;
using FIntBulkData = TBulkData<int32>;
using FFloatBulkData = TBulkData<float>;
 
class FFormatContainer
{
    friend class UBodySetup;
 
    TSortedMap<FName, FByteBulkData*, FDefaultAllocator, FNameFastLess> Formats;
public:
    ~FFormatContainer()
    {
        FlushData();
    }
    bool Contains(FName Format) const
    {
        return Formats.Contains(Format);
    }
    void GetContainedFormats(TArray<FName>& OutFormats) const
    {
        Formats.GenerateKeyArray(OutFormats);
    }
    FByteBulkData& GetFormat(FName Format)
    {
        FByteBulkData* Result = Formats.FindRef(Format);
        if (!Result)
        {
            Result = new FByteBulkData;
            Formats.Add(Format, Result);
        }
        return *Result;
    }
    void FlushData()
    {
        for (const TPair<FName, FByteBulkData*>& Format : Formats)
        {
            FByteBulkData* BulkData = Format.Value;
            delete BulkData;
        }
        Formats.Empty();
    }
    
    void DeepCopy(const FFormatContainer& Other)
    {
        // Safely clean up any entries that the current FFormatContainer has before creating/adding copies from the provided container.
        FlushData();
 
        for (const TPair<FName, FByteBulkData*>& Format : Other.Formats)
        {
            FByteBulkData* Copy = new FByteBulkData(*Format.Value);
            Formats.Add(Format.Key, Copy);
        }
    }
 
    COREUOBJECT_API void Serialize(FArchive& Ar, UObject* Owner, const TArray<FName>* FormatsToSave = nullptr, bool bSingleUse = true, uint16 InAlignment = DEFAULT_ALIGNMENT, bool bInline = true, bool bMapped = false);
    COREUOBJECT_API void SerializeAttemptMappedLoad(FArchive& Ar, UObject* Owner);
};
 
class FBulkDataRequest
{
public:
    enum class EStatus : uint32
    {
        None,
        Pending,
        Ok,
        Cancelled,
        Error
    };
 
protected:
    class IHandle
    {
    public:
        virtual ~IHandle();
 
        virtual void AddRef() = 0;
        virtual void Release() = 0;
        virtual uint32 GetRefCount() const = 0;
 
        virtual FBulkDataRequest::EStatus GetStatus() const = 0;
        virtual bool Cancel() = 0;
        virtual bool Wait(uint32 Milliseconds) = 0;
        virtual void UpdatePriority(const EAsyncIOPriorityAndFlags Priority) = 0;
    };
 
public:
    using FCompletionCallback = TFunction<void(EStatus)>;
 
    static constexpr EAsyncIOPriorityAndFlags DefaultPriority = AIOP_BelowNormal;
 
    FBulkDataRequest() = default;
 
    ~FBulkDataRequest() = default;
 
    FBulkDataRequest(FBulkDataRequest&&) = default;
    FBulkDataRequest& operator=(FBulkDataRequest&&) = default;
    
    FBulkDataRequest(const FBulkDataRequest&) = delete;
    FBulkDataRequest& operator=(const FBulkDataRequest&) = delete;
 
    EStatus GetStatus() const { return Handle.IsValid() ? Handle->GetStatus() : EStatus::None; }
 
    bool IsNone() const { return FBulkDataRequest::EStatus::None == GetStatus(); }
 
    bool IsPending() const { return FBulkDataRequest::EStatus::Pending == GetStatus(); }
 
    bool IsOk() const { return FBulkDataRequest::EStatus::Ok == GetStatus(); }
 
    bool IsCompleted() const { return GetStatus() > EStatus::Pending; }
 
    void Cancel() { if (Handle.IsValid()) { Handle->Cancel(); } }
 
    void Reset() { Handle.SafeRelease(); }
 
protected:
    friend class FHandleBase;
    friend class FChunkBatchReadRequest;
    friend class FBulkDataBatchRequest;
    
    FBulkDataRequest(FBulkDataRequest::IHandle* InHandle)
        : Handle(InHandle)
    {
        check(InHandle != nullptr);
    }
 
    TRefCountPtr<IHandle> Handle;
};
 
using FBulkDataBatchReadRequest = FBulkDataRequest;
 
class FBulkDataBatchRequest : public FBulkDataRequest
{
public:
    class FBatchHandle;
 
private:
    class FBuilder
    {
    public:
        COREUOBJECT_API ~FBuilder();
        FBuilder(const FBuilder&) = delete;
        FBuilder& operator=(const FBuilder&) = delete;
 
    protected:
        COREUOBJECT_API explicit FBuilder(int32 MaxCount);
        COREUOBJECT_API FBulkDataBatchRequest::FBatchHandle& GetBatch();
        COREUOBJECT_API void IssueBatch(FBulkDataBatchRequest* OutRequest, FCompletionCallback&& Callback);
 
        int32 BatchCount = 0;
        int32 NumLoaded = 0;
 
    private:
        int32 BatchMax = -1;
        TRefCountPtr<FBulkDataBatchRequest::FBatchHandle> Batch;
    };
 
public: 
    using FBulkDataRequest::FBulkDataRequest;
 
    COREUOBJECT_API void Wait();
 
    COREUOBJECT_API bool WaitFor(uint32 Milliseconds);
 
    COREUOBJECT_API bool WaitFor(const FTimespan& WaitTime);
 
    COREUOBJECT_API void UpdatePriority(const EAsyncIOPriorityAndFlags Priority);
 
    class FBatchBuilder : public FBuilder
    {
    public:
        COREUOBJECT_API FBatchBuilder(int32 MaxCount);
        COREUOBJECT_API bool IsEmpty() const;
        COREUOBJECT_API FBatchBuilder& Read(FBulkData& BulkData, EAsyncIOPriorityAndFlags Priority = DefaultPriority);
        FBatchBuilder& Read(const FBulkData& BulkData, uint64 Offset, uint64 Size, EAsyncIOPriorityAndFlags Priority, FIoBuffer& Dst)
        {
            return Read(BulkData, Offset, Size, Priority, Dst, nullptr);
        }
        FBatchBuilder& Read(const FBulkData& BulkData, uint64 Offset, uint64 Size, EAsyncIOPriorityAndFlags Priority, FIoBuffer& Dst, FBulkDataBatchReadRequest& OutRequest)
        {
            return Read(BulkData, Offset, Size, Priority, Dst, &OutRequest);
        }
 
        COREUOBJECT_API void Issue(FCompletionCallback&& Callback, FBulkDataBatchRequest& OutRequest);
        COREUOBJECT_API void Issue(FBulkDataBatchRequest& OutRequest);
        COREUOBJECT_API void Issue();
 
    private:
        COREUOBJECT_API FBatchBuilder& Read(const FBulkData& BulkData, uint64 Offset, uint64 Size, EAsyncIOPriorityAndFlags Priority, FIoBuffer& Dst, FBulkDataBatchReadRequest* OutRequest);
    };
 
    class FScatterGatherBuilder : public FBuilder
    {
    public:
        COREUOBJECT_API FScatterGatherBuilder(int32 MaxCount);
        COREUOBJECT_API FScatterGatherBuilder& Read(const FBulkData& BulkData, uint64 Offset = 0, uint64 Size = MAX_uint64);
        COREUOBJECT_API void Issue(FIoBuffer& Dst, EAsyncIOPriorityAndFlags Priority, FCompletionCallback&& Callback, FBulkDataBatchRequest& OutRequest);
 
    private:
        struct FRequest
        {
            const FBulkData* BulkData   = nullptr;
            uint64 Offset               = 0;
            uint64 Size                 = MAX_uint64;
        };
 
        TArray<FRequest, TInlineAllocator<8>> Requests;
    };
 
    static FBatchBuilder NewBatch(int32 MaxCount = -1) { return FBatchBuilder(MaxCount); }
 
    static FScatterGatherBuilder ScatterGather(int32 MaxCount = -1) { return FScatterGatherBuilder(MaxCount); }
};