IoStoreOnDemand.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "Containers/Map.h"
#include "Containers/UnrealString.h"
#include "Containers/StringFwd.h"
#include "Containers/SharedString.h"
#include "IO/OnDemandError.h"
#include "IO/OnDemandHostGroup.h"
#include "IO/OnDemandToc.h"
#include "IO/PackageId.h"
#include "Misc/EnumClassFlags.h"
#include "Features/IModularFeature.h"
#include "Misc/Optional.h"
#include "Modules/ModuleInterface.h"
#include "Templates/SharedPointer.h"
#include "UObject/NameTypes.h"
 
#define UE_API IOSTOREONDEMANDCORE_API
 
struct FAnalyticsEventAttribute;
 
// Custom initialization allows users to control when
// the system should be initialized.
#if !defined(UE_IAS_CUSTOM_INITIALIZATION)
    #define UE_IAS_CUSTOM_INITIALIZATION 0
#endif
 
UE_API DECLARE_LOG_CATEGORY_EXTERN(LogIoStoreOnDemand, Log, All);
UE_API DECLARE_LOG_CATEGORY_EXTERN(LogIas, Log, All);
 
namespace UE::IoStore
{
 
using FSharedOnDemandIoStore        = TSharedPtr<class IOnDemandIoStore, ESPMode::ThreadSafe>;
using FWeakOnDemandIoStore          = TWeakPtr<class IOnDemandIoStore, ESPMode::ThreadSafe>;
using FSharedInternalContentHandle  = TSharedPtr<class FOnDemandInternalContentHandle, ESPMode::ThreadSafe>;
using FSharedInternalInstallRequest = TSharedPtr<class FOnDemandInternalInstallRequest, ESPMode::ThreadSafe>;
 
class FOnDemandRequest
{
public:
    enum EStatus : uint8
    {
        None,
        Pending,
        PendingCallbacks,
        Ok,
        Cancelled,
        Error
    };
    virtual ~FOnDemandRequest() = default;
    virtual EStatus GetStatus() const = 0;
    bool IsNone() const { return EStatus::None == GetStatus(); }
    bool IsPending() const { return EStatus::Pending == GetStatus(); }
    bool IsPendingCallbacks() const { return EStatus::PendingCallbacks == GetStatus(); }
    bool IsOk() const { return EStatus::Ok == GetStatus(); }
    bool IsCancelled() const { return EStatus::Cancelled == GetStatus(); }
    bool IsError() const { return EStatus::Error == GetStatus(); }
    bool IsCompleted() const { return static_cast<uint8>(EStatus::Pending) < static_cast<uint8>(GetStatus()); }
 
protected:
    FOnDemandRequest() = default;
};
 
class FOnDemandContentHandle
{
public:
    UE_API FOnDemandContentHandle();
    UE_API ~FOnDemandContentHandle();
    void Reset() { Handle.Reset(); }
    bool IsValid() const { return Handle.IsValid(); }
    UE_API static FOnDemandContentHandle Create();
    UE_API static FOnDemandContentHandle Create(FSharedString DebugName);
    UE_API static FOnDemandContentHandle Create(FStringView DebugName);
    UE_API friend FString LexToString(const FOnDemandContentHandle& Handle);
 
    bool operator==(FOnDemandContentHandle& Other) const
    {
        return Handle == Other.Handle;
    }
 
private:
    friend class FOnDemandIoStore;
    friend class FOnDemandContentInstaller;
    FSharedInternalContentHandle Handle;
};
 
struct FOnDemandRegisterHostGroupArgs
{
    FName HostGroupName;
    TArray<FString> HostNames;
    FString TestUrl;
    bool bUseSecureHttp = false;
};
 
struct FOnDemandRegisterHostGroupResult
{
    bool IsOk() const { return Error.IsSet() == false; }
    FOnDemandHostGroup HostGroup;
    TOptional<UE::UnifiedError::FError> Error;
};
 
enum class EOnDemandMountOptions
{
    StreamOnDemand          = 1 << 0,
    InstallOnDemand         = 1 << 1,
    CallbackOnGameThread    = 1 << 2,
    WithSoftReferences      = 1 << 3,
    ForceNonSecureHttp      = 1 << 4,
};
ENUM_CLASS_FLAGS(EOnDemandMountOptions);
 
struct FOnDemandMountArgs
{
    TUniquePtr<FOnDemandToc> Toc;
    FString MountId;
    FString TocRelativeUrl;
    FString FilePath;
    FName HostGroupName = FOnDemandHostGroup::DefaultName;
    FOnDemandHostGroup HostGroup;
    EOnDemandMountOptions Options = EOnDemandMountOptions::StreamOnDemand;
};
 
struct FOnDemandMountResult
{
    FString MountId;
    FIoStatus Status;
    double DurationInSeconds = 0.0;
 
    UE_API void LogResult();
};
 
using FOnDemandMountCompleted = TUniqueFunction<void(FOnDemandMountResult)>;
 
enum class EOnDemandInstallOptions
{
    None                        = 0,
    CallbackOnGameThread        = 1 << 0,
    InstallSoftReferences       = 1 << 1,
    InstallOptionalBulkData     = 1 << 2,
    DoNotDownload               = 1 << 3,
    AllowMissingDependencies    = 1 << 4
};
ENUM_CLASS_FLAGS(EOnDemandInstallOptions);
 
struct FOnDemandInstallArgs 
{
    FString MountId;
    TArray<FString> TagSets;
    TArray<FPackageId> PackageIds;
    FOnDemandContentHandle ContentHandle;
    EOnDemandInstallOptions Options = EOnDemandInstallOptions::None;
    int32 Priority = 0;
    FSharedString DebugName;
};
 
struct FOnDemandInstallProgress
{
    uint64 TotalContentSize = 0;
    uint64 TotalInstallSize = 0;
    uint64 CurrentInstallSize = 0;
 
    FOnDemandInstallProgress& Combine(const FOnDemandInstallProgress& Other)
    {
        TotalContentSize += Other.TotalContentSize;
        TotalInstallSize += Other.TotalInstallSize;
        CurrentInstallSize += Other.CurrentInstallSize;
        return *this;
    }
 
    uint64 GetTotalDownloadSize() const
    {
        return TotalInstallSize;
    }
 
    uint64 GetAlreadyDownloadedSize() const
    {
        return CurrentInstallSize;
    }
 
    float GetRelativeProgress() const 
    {
        const double Progress = (TotalInstallSize > 0) ?
            FMath::Clamp(double(CurrentInstallSize) / double(TotalInstallSize), 0.0, 1.0) :
            0;
 
        return float(Progress);
    }
 
    float GetAbsoluteProgress() const
    {
        const double Progress = (TotalContentSize > 0) ?
            FMath::Clamp(double(GetCachedSize()) / double(TotalContentSize), 0.0, 1.0) :
            0;
 
        return float(Progress);
    }
 
    uint64 GetCachedSize() const 
    {
        return TotalContentSize - TotalInstallSize + CurrentInstallSize;
    }
 
    uint64 GetTotalSize() const
    {
        return TotalContentSize;
    }
};
 
using FOnDemandInstallProgressed = TFunction<void(FOnDemandInstallProgress)>;
 
struct FOnDemandInstallResult
{
    bool IsOk() const { return Error.IsSet() == false; }
    double DurationInSeconds = 0.0;
    FOnDemandInstallProgress Progress;
    TOptional<UE::UnifiedError::FError> Error;
};
 
using FOnDemandInstallCompleted = TUniqueFunction<void(FOnDemandInstallResult)>;
 
class FOnDemandInstallRequest final
    : public FOnDemandRequest
{
    friend class FOnDemandIoStore;
public:
    UE_API FOnDemandInstallRequest();
    UE_API FOnDemandInstallRequest(FOnDemandInstallRequest&&);
    UE_API FOnDemandInstallRequest& operator=(FOnDemandInstallRequest&&);
    UE_API ~FOnDemandInstallRequest();
    UE_API virtual EStatus GetStatus() const override;
    UE_API void Cancel();
    UE_API void UpdatePriority(int32 NewPriority);
 
private:
    UE_API FOnDemandInstallRequest(FWeakOnDemandIoStore IoStore, FSharedInternalInstallRequest InternalRequest);
    FOnDemandInstallRequest(const FOnDemandInstallRequest&) = delete;
    FOnDemandInstallRequest& operator=(const FOnDemandInstallRequest&) = delete;
 
    FWeakOnDemandIoStore IoStore;   
    FSharedInternalInstallRequest Request;
};
 
enum class EOnDemandPurgeOptions
{
    None = 0,
    CallbackOnGameThread = 1 << 0,
    Defrag = 1 << 1,
};
ENUM_CLASS_FLAGS(EOnDemandPurgeOptions)
 
 
struct FOnDemandPurgeArgs
{
    EOnDemandPurgeOptions Options = EOnDemandPurgeOptions::None;
    TOptional<uint64> BytesToPurge;
};
 
struct FOnDemandPurgeResult
{
    bool IsOk() const { return Error.IsSet() == false; }
    double DurationInSeconds = 0.0;
    TOptional<UE::UnifiedError::FError> Error;
};
 
using FOnDemandPurgeCompleted = TUniqueFunction<void(FOnDemandPurgeResult)>;
 
enum class EOnDemandDefragOptions
{
    None = 0,
    CallbackOnGameThread = 1 << 0,
};
ENUM_CLASS_FLAGS(EOnDemandDefragOptions)
 
 
struct FOnDemandDefragArgs
{
    EOnDemandDefragOptions Options = EOnDemandDefragOptions::None;
    TOptional<uint64> BytesToFree;
};
 
struct FOnDemandDefragResult
{
    bool IsOk() const { return Error.IsSet() == false; }
    double DurationInSeconds = 0.0;
    TOptional<UE::UnifiedError::FError> Error;
};
 
using FOnDemandDefragCompleted = TUniqueFunction<void(FOnDemandDefragResult)>;
 
enum class EOnDemandGetInstallSizeOptions
{
    None                    = 0,
    IncludeSoftReferences   = 1 << 0,
    IncludeOptionalBulkData = 1 << 1
};
ENUM_CLASS_FLAGS(EOnDemandGetInstallSizeOptions);
 
struct FOnDemandGetInstallSizeArgs 
{
    FString MountId;
    TArray<FString> TagSets;
    TArray<FPackageId> PackageIds;
    EOnDemandGetInstallSizeOptions Options = EOnDemandGetInstallSizeOptions::None;
    FOnDemandContentHandle ContentHandle;
};
 
struct FOnDemandInstallSizeResult
{
    uint64  InstallSize = 0;
    TOptional<uint64> DownloadSize = 0;
};
 
enum class EOnDemandGetCacheUsageOptions
{
    None = 0,
    DumpHandlesToLog = 1 << 0,
    DumpHandlesToResults = 1 << 1,
};
ENUM_CLASS_FLAGS(EOnDemandGetCacheUsageOptions);
 
struct FOnDemandGetCacheUsageArgs
{
    EOnDemandGetCacheUsageOptions Options = EOnDemandGetCacheUsageOptions::None;
};
 
struct FOnDemandInstallHandleCacheUsage
{
    UPTRINT         HandleId = 0;
    FSharedString   DebugName;
    uint64          ReferencedBytes = 0;
};
 
struct FOnDemandInstallCacheUsage
{
    uint64 MaxSize = 0;
    uint64 TotalSize = 0;
    uint64 ReferencedBlockSize = 0;
    uint64 ReferencedSize = 0;
    uint64 FragmentedChunksSize = 0;
 
    // Only populated if DumpHandlesToResults is specified
    TArray<FOnDemandInstallHandleCacheUsage> ReferencedBytesByHandle;
 
    UE_API friend FStringBuilderBase& operator<<(FStringBuilderBase& Sb, const FOnDemandInstallCacheUsage& CacheUsage);
};
 
struct FOnDemandStreamingCacheUsage
{
    uint64 MaxSize = 0;
    uint64 TotalSize = 0;
 
    UE_API friend FStringBuilderBase& operator<<(FStringBuilderBase& Sb, const FOnDemandStreamingCacheUsage& CacheUsage);
};
 
struct FOnDemandCacheUsage
{
    FOnDemandInstallCacheUsage InstallCache;
    FOnDemandStreamingCacheUsage StreamingCache;
};
 
struct FOnDemandVerifyCacheResult
{
    bool IsOk() const { return Error.IsSet() == false; }
    double DurationInSeconds = 0.0;
    TOptional<UE::UnifiedError::FError> Error;
};
 
using FOnDemandVerifyCacheCompleted = TUniqueFunction<void(FOnDemandVerifyCacheResult)>;
 
class IAnalyticsRecording
{
public:
    IAnalyticsRecording() = default;
    virtual ~IAnalyticsRecording() = default;
 
    virtual void Report(TArray<FAnalyticsEventAttribute>& OutAnalyticsArray) const = 0;
    
    virtual void StopRecording() = 0;
};
 
struct FOnDemandImmediateAnalytic
{
    FString EventName;
    TArray<FAnalyticsEventAttribute> AnalyticsArray;
};
 
struct FOnDemandImmediateAnalyticHandler
{
    TUniqueFunction<void(FOnDemandImmediateAnalytic)> EventHandler;
};
 
enum class EOnDemandStreamingOptions
{
    Default                     = 0,
    OptionalBulkDataDisabled    = (1 << 0)
};
ENUM_CLASS_FLAGS(EOnDemandStreamingOptions);
 
class IOnDemandIoStore
{
public:
    virtual ~IOnDemandIoStore() = default;
    virtual FIoStatus InitializePostHotfix() = 0;
    virtual FOnDemandRegisterHostGroupResult RegisterHostGroup(FOnDemandRegisterHostGroupArgs&& Args) = 0;
    virtual void Mount(FOnDemandMountArgs&& Args, FOnDemandMountCompleted&& OnCompleted) = 0;
    virtual FIoStatus Unmount(FStringView MountId) = 0;
    virtual FOnDemandInstallRequest Install(
            FOnDemandInstallArgs&& Args,
            FOnDemandInstallCompleted&& OnCompleted,
            FOnDemandInstallProgressed&& OnProgress = nullptr) = 0;
    virtual void Purge(FOnDemandPurgeArgs&& Args, FOnDemandPurgeCompleted&& OnCompleted) = 0;
    virtual void Defrag(FOnDemandDefragArgs&& Args, FOnDemandDefragCompleted&& OnCompleted) = 0;
    virtual void Verify(FOnDemandVerifyCacheCompleted&& OnCompleted) = 0;
    virtual TIoStatusOr<FOnDemandInstallSizeResult> GetInstallSize(const FOnDemandGetInstallSizeArgs& Args) const = 0;
    virtual FIoStatus GetInstallSizesByMountId(const FOnDemandGetInstallSizeArgs& Args, TMap<FString, uint64>& OutSizesByMountId) const = 0;
    virtual FOnDemandCacheUsage GetCacheUsage(const FOnDemandGetCacheUsageArgs& Args) const = 0;
    virtual void DumpMountedContainersToLog() const = 0;
    virtual bool IsOnDemandStreamingEnabled() const = 0;
    virtual void SetStreamingOptions(EOnDemandStreamingOptions Options) = 0;
    virtual void ReportAnalytics(TArray<FAnalyticsEventAttribute>& OutAnalyticsArray) const = 0;
    virtual TUniquePtr<IAnalyticsRecording> StartAnalyticsRecording() const = 0;
    virtual void OnImmediateAnalytic(FOnDemandImmediateAnalyticHandler EventHandler) = 0;
 
private:
    virtual FIoStatus Initialize() = 0;
    virtual void CancelInstallRequest(FSharedInternalInstallRequest InstallRequest) = 0;
    virtual void UpdateInstallRequestPriority(FSharedInternalInstallRequest InstallRequest, int32 NewPriority) = 0;
    virtual void ReleaseContent(class FOnDemandInternalContentHandle& ContentHandle) = 0;
 
    friend class FIoStoreOnDemandCoreModule;
    friend class FOnDemandInternalContentHandle;
    friend class FOnDemandInstallRequest;
};
 
class IOnDemandIoStoreFactory
    : public IModularFeature
{
public:
    UE_API static FName FeatureName;
    virtual IOnDemandIoStore* CreateInstance() = 0;
    virtual void DestroyInstance(IOnDemandIoStore* Instance) = 0;
};
 
UE_API IOnDemandIoStore* TryGetOnDemandIoStore();
UE_API IOnDemandIoStore& GetOnDemandIoStore();
 
} // namespace UE::IoStore
 
#undef UE_API