class `PersistentCache`

Inherits: std::enable_shared_from_this<PersistentCache>

Cache that will persist between application runs.

Public

Constructors

PersistentCache

PersistentCache(PrivatelyConstruct)

Methods

~PersistentCache

~PersistentCache() = default

Initialize

void Initialize(const Path &cacheFolder)

Initializes the cache.

Must be called at least once before using the cache. Can be called multiple times in which the cache will be reinitialized with the provided settings.

cacheFolder: Absolute path to folder in which the cache will store its contents.

SetMaximumCacheSize

void SetMaximumCacheSize(u64 sizeLimitInMb = 2048)

Changes the maximum size of the cache.

May trigger eviction.

sizeLimitInMb: Cache size limit in megabytes. The cache will attempt to stay below this number, but may exceed it momentarily if there are a lot of operations in progress and entries cannot be evicted in time.

Update

void Update()

To be called every frame.

RunEvictionIfRequired

void RunEvictionIfRequired()

Evicts cache entries if the cache contains more data than it can hold.

RunEviction

void RunEviction(u64 targetSizeInMb)

Evicts files from the cache until adequate amount of space has been acquired.

SetEntry

bool SetEntry(const Path &path, const SPtr<IReflectable> &data, PersistentCachePriority priority = PersistentCachePriority::Normal, bool blocking = true)

Adds a new entry to the cache, or overrides an existing one.

path: Path at which to store the data. Relative to the cache folder.
data: Data to store or null to clear an existing entry.
priority: Priority that determines when is the entry evicted. Entries with lower priority will be evicted before ones with higher priority.
blocking: If false, the entry will not be cleared if there are currently any read or write locks acquired for it (i.e. it's used by another thread). Otherwise we will block the calling until the locks are released, and then update the entry.

Returns: True if the entry was added to the cache, or false if the operation failed. Failure can happen if the entry exceeds the size of the cache.

TryGetEntry

SPtr<IReflectable> TryGetEntry(const Path &path)

Attempts to retrieve an entry at the specified path.

path: Path of the entry relative to the cache folder.

Returns: Data at the provided path if found or null otherwise.

staticCreate

static SPtr<PersistentCache> Create()

Creates a new persistent cache object.

Private

Methods

NotifyOperationDidStart

void NotifyOperationDidStart(const Path &path, CacheOperationType type)

Notifies the cache that a new CacheOperation has started.

Caller must be holding the cache mutex lock during the call.

NotifyOperationWillEnd

void NotifyOperationWillEnd(const Path &path, CacheOperationType type)

Notifies the cache that a CacheOperation is about to end.

AcquireReadOperation

TOptional<CacheOperation> AcquireReadOperation(const Path &path)

Attempts to acquire a read operation on the provided cache entry.

You should only read from a cache entry if there is an active read operation for the entry.

path: Path to the entry, relative to the root cache folder.

Returns: Operation if successful, or null otherwise.

AcquireWriteOperation

TOptional<CacheOperation> AcquireWriteOperation(const Path &path, bool createNewIfMissing, PersistentCachePriority priority, bool blocking = true)

Attempts to acquire a write operation on the provided cache entry.

You should only write to a cache entry if there is an active write operation for the entry.

path: Path to the entry, relative to the root cache folder.
createNewIfMissing: If the entry doesn't yet exist, this will create a new entry. If not enabled a null operation will be returned for non-existing entries.
priority: If creating a new entry, priority to use when creating it.
blocking: If true, the calling thread will block until all other operations on the resource complete. If false, the method with fail to acquire an operation if there are any other operation in progress.

Returns: Operation if successful, or null otherwise.

GetPackageForEntry

SPtr<Package> GetPackageForEntry(const CacheOperation &operation) const

Retrieves a package in which the cache entry is stored.

Caller must acquire a read operation for the entry beforehand.

SetPackageForEntry

bool SetPackageForEntry(const CacheOperation &operation, const SPtr<Package> &package)

Adds a new package to the cache.

Caller must acquire a write operation for the entry beforehand. Will trigger eviction if the cache is full. Returns false if the entry doesn't fit into the cache.

GetPackagePathForEntry

Path GetPackagePathForEntry(const Path &path) const

Converts a path of a cache entry (relative to the cache) to an absolute path the package is being stored at in the file system.

DeleteEntry

void DeleteEntry(const CacheOperation &operation)

Deletes a cache entry associated with the provided operation.

Operation must be have a Write type.

WaitForAllOperationsToComplete

void WaitForAllOperationsToComplete(Lock &lock)

Waits for both read and write operation to complete for all cache entries.

WriteDirtyMetaData

void WriteDirtyMetaData()

Iterates over all entries with dirty meta-data, and writes the meta-data into their packages.

SharedDeleter

void SharedDeleter(PersistentCache *cache)

Called when the shared pointer to this goes out of scope.

Fields

mCacheFolder

Path mCacheFolder

mUsedCacheSizeInBytes

u64 mUsedCacheSizeInBytes

mSizeLimitInBytes

u64 mSizeLimitInBytes

mEntries

UnorderedMap<Path, CacheEntry> mEntries

mIsAnyEntryMetaDataDirty

bool mIsAnyEntryMetaDataDirty

mTotalActiveReadOperationCount

u32 mTotalActiveReadOperationCount

mTotalActiveWriteOperationCount

u32 mTotalActiveWriteOperationCount

mMutex

Mutex mMutex

mOperationCompletedSignal

Signal mOperationCompletedSignal