Unreal Engine 4.26 Documentation

Unreal Engine 4.27 Documentation

Unreal Engine 5.0 Documentation

Unreal Engine 5.1 Documentation

Unreal Engine 5.2 Documentation

Unreal Engine 5.3 Documentation

> Unreal Engine API Reference > Runtime > Core > Misc > FPreloadableFile

Light Theme

Dark Theme

FPreloadableFile

A read-only archive that provides access to a File on disk, similar to [FArchiveFileReaderGeneric](API\Runtime\Core\HAL\FArchiveFileReaderGeneric) provided by [FFileManagerGeneric](API\Runtime\Core\HAL\FFileManagerGeneric), but with support for asynchronous preloading and priming.

Windows

MacOS

Linux

Inheritance Hierarchy

FArchiveState

FArchive

FPreloadableFile

References

Module	Core
Header	/Engine/Source/Runtime/Core/Public/Misc/PreloadableFile.h
Include	#include "Misc/PreloadableFile.h"

Syntax

class FPreloadableFile : public FArchive

Remarks

A read-only archive that provides access to a File on disk, similar to FArchiveFileReaderGeneric provided by FFileManagerGeneric, but with support for asynchronous preloading and priming.

This class supports two mutually-exclusive modes: PreloadBytes: A lower-level asynchronous archive is opened during initialization and size is read. After initialization, when StartPreload is called, an array of bytes equal in size to the file's size is allocated, and an asynchronous ReadRequest is sent to the IAsyncReadFileHandle to read the first <PageSize> bytes of the file. Upon completion of each in-flight ReadRequest, another asynchronous ReadRequest is issued, until the entire file has been read. If serialize functions are called beyond the bytes of the file that have been cached so far, they requests are satisfied by synchronous reads.

Activate this mode by passing Flags::PreloadBytes to InitializeAsync. PreloadHandle: A lower-level FArchive is opened for the file using IFileManager::Get().CreateFileReader; this call is made asynchronously on a TaskGraph thread. Optionally, a precache request is sent to the lower-level FArchive for the first <PrimeSize> bytes; this call is also made asynchronously. The created and primed lower-level FArchive can then be detached from this class and handed off to a new owner.

Activate this mode by passing Flags::OpenHandle and (optionally, for the precache request) Flags::Prime to InitializeAsync.

This class also supports registration of the members of this class by filename, which other systems in the engine can use to request an FArchive for the preload file, if it exists, replacing a call they would otherwise make to IFileManager::Get().CreateFileReader.

This class is not threadsafe. The public interface can be used at the same time as internal asynchronous tasks are executing, but the public interface can not be used from multiple threads at once.

Constructors

	Name	Description
	FPreloadableFile ( const TCHAR* FileName )

Destructors

	Name	Description
	~FPreloadableFile()

Functions

	Name	Description
bool	AllocateCache()	When in PreloadBytes mode, allocate if necessary the memory for the preloaded bytes.
FArchive ...	DetachLowerLevel()	Return the LowerLevel FArchive if it has been allocated.
void	InitializeAsync ( uint32 InFlags, int64 PrimeSize )	Initialize the FPreloadableFile asynchronously, performing FileOpen operations on another thread.
bool	IsCacheAllocated()	Return whether the cache is currently allocated.
bool	IsInitialized()	Return whether InitializeAsync has completed.
bool	IsPreloading()	Return whether preloading is in progress.
void	ReleaseCache()	Free all memory used by the cache or for preloading (calling StopPreload if necessary).
void	SetPageSize ( int64 PageSize )	Initialization.
bool	StartPreload()	Preloading.
void	StopPreload()	Cancel any current asynchronous ReadRequests and wait for the asynchronous work to exit.
bool	TryRegister ( const TSharedPtr< FPreloadableFile ... )	Registration.
FArchive ...	TryTakeArchive ( const TCHAR* FileName )	Look up an FPreloadableFile instance registered for the given FileName, and return an FArchive from it.
bool	UnRegister ( const TSharedPtr< FPreloadableFile ... )	Remove the FPreloadableFile instance if it is registered for its FileName.
void	WaitForInitialization()	Wait for InitializeAsync to complete if it is running, otherwise return immediately.

Overridden from FArchive

	Name	Description
bool	Close()	Attempts to close and finalize any handles used for backing data storage, returns true if it succeeded.
void	Seek ( int64 InPos )	Attempts to set the current offset into backing data storage, this will do nothing if there is no storage.
void	Serialize ( void* V, int64 Length )	FArchive.

Overridden from FArchiveState

	Name	Description
FString	GetArchiveName()	Returns the name of the Archive.
int64	Tell()	Returns the current location within the backing data storage, which can possibly be passed to Seek later to restore a read/write location.
int64	TotalSize()	Return the size of the file, or -1 if the file does not exist.

Enums

	Name	Description
	Flags

Typedefs

Name	Description
FOnInitialized

Constants

Name	Description
DefaultPageSize
DefaultPrimeSize
RegisteredFiles	Map used for TryTakeArchive registration.

Help shape the future of Unreal Engine documentation! Tell us how we're doing so we can serve you better.

Take our survey

Dismiss