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 > FPreloadableArchive

Light Theme

Dark Theme

FPreloadableArchive

A read-only archive that adds support for asynchronous preloading and priming to an inner archive.

Choose your operating system:

Windows

macOS

Linux

Inheritance Hierarchy

FArchiveState

FArchive

FPreloadableArchive

FPreloadableFile

References

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

Syntax

class FPreloadableArchive : public FArchive

Remarks

A read-only archive that adds support for asynchronous preloading and priming to an inner archive.

This class supports two mutually-exclusive modes: PreloadBytes: An asynchronous inner archive is opened using the passed-in CreateAsyncArchive function; this call is made asynchronously on a TaskGraph thread. The size is read during initialization. After initialization, when StartPreload is called, an array of bytes equal in size to the inner archive'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 an FCreateArchive to InitializeAsync. PreloadHandle: A synchronous inner archive is opened using the passed-in CreateArchive function; this call is made asynchronously on a TaskGraph thread. Optionally, a precache request is sent to the inner archive 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 an FCreateAsyncArchive and (optionally, for the precache request) Flags::Prime to InitializeAsync.

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.

Variables

	Name	Description
FString	ArchiveName
TUniquePtr< IAs...	AsynchronousHandle	The handle used for PreloadBytes mode, to fulfull ReadReqeusts.
TAtomic< bool >	bInitialized	Threadsafe variable that returns true only after all asynchronous initialization is complete.
bool	bIsInlineReadComplete	Set to true during the ReadRequest call to allow us to detect if OnReadComplete is called inline on the same thread from ReadRequest.
TAtomic< bool >	bIsPreloading	Threadsafe variable that is true only during the period between initialization until Preloading stops (either due to EOF reached or due to Serialize turning it off.
TAtomic< bool >	bIsPreloadingPaused	Variable that is set to true from the public interface thread to signal that (temporarily) no further ReadRequests should be sent when the currently active one completes.
bool	bReadCompleteWasCalledInline	Set to true if OnReadComplete is called inline on the same thread from ReadRequest; we need special handling for this case.
uint8 *	CacheBytes	An array of bytes of size Size.
TAtomic< int64 ...	CacheEnd	Number of bytes in CacheBytes that have already been read.
int64	PageSize	The number of bytes requested from the AsynchronousHandle in each ReadRequest.
FEvent *	PendingAsyncComplete	An Event used for synchronization with asynchronous tasks - InitializingAsync or receiving ReadRequests from the AsynchronousHandle.
int64	Pos	The Offset into the file or preloaded bytes that will be used in the next call to Serialize.
FCriticalSectio...	PreloadLock	CriticalSection used to synchronize access to the CacheBytes.
TArray< IAsyncR...	RetiredRequests	ReadRequests that have completed but we have not yet deleted.
FPreloadableArc...	SavedReadCompleteArguments
int64	Size	The number of bytes in the file.
TUniquePtr< FAr...	SynchronousArchive	The archive used in PreloadHandle mode or to service Serialize requests that are beyond CacheEnd when in PreloadBytes mode.

Constructors

	Name	Description
	FPreloadableArchive ( FStringView ArchiveName )

Destructors

	Name	Description
	~FPreloadableArchive()

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	FreeRetiredRequests()
void	InitializeAsync ( FCreateArchive&& InCreateArchiveFu..., uint32 InFlags, int64 PrimeSize )	Initialize the FPreloadableFile asynchronously, performing FileOpen operations on another thread.
void	InitializeAsync ( FCreateAsyncArchive&& InCreateAsyn..., uint32 InFlags, int64 PrimeSize )	Initialize the FPreloadableFile asynchronously, performing FileOpen operations on another thread.
void	InitializeInternal ( FCreateArchive&& InCreateArchiveFu..., FCreateAsyncArchive&& InCreateAsyn..., uint32 Flags, int64 PrimeSize )	Helper function for InitializeAsync, called from a TaskGraph thread.
void	InitializeInternalAsync ( FCreateArchive&& InCreateArchiveFu..., FCreateAsyncArchive&& InCreateAsyn..., uint32 InFlags, int64 PrimeSize )	Helper function for InitializeAsync, sets up the asynchronous call to InitializeInternal
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	OnReadComplete ( bool bCanceled, IAsyncReadRequest* ReadRequest )
void	PausePreload()
void	ReleaseCache()	Free all memory used by the cache or for preloading (calling StopPreload if necessary).
void	ResumePreload()
bool	ResumePreloadNonRecursive()
void	SerializeSynchronously ( void* V, int64 Length )
void	SetPageSize ( int64 PageSize )	Initialization.
bool	StartPreload()	Preloading.
void	StopPreload()	Cancel any current asynchronous ReadRequests and wait for the asynchronous work to exit.
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.

Classes

	Name	Description
	FSavedReadCompleteArguments	Saved values from the inline OnReadComplete call

Enums

	Name	Description
	Flags

Typedefs

Name	Description
FCreateArchive
FCreateAsyncArchive

Constants

Name	Description
DefaultPageSize
DefaultPrimeSize