Struct FileBackedLfuCache

pub struct FileBackedLfuCache<K, T>
where
    K: Key,
    T: AsyncFileRepr,
{ /* private fields */ }

A LFU (least frequently used) cache layered on top a file system, where files can be accessed using their unique keys.

Files can be loaded from disk and stored in cache. When evicted from cache, the file is automatically flushed to disk.

Note that if you are caching persistent data, you should call Self::flush_all before dropping this cache. Otherwise new items and changes in the cache will be lost.

Implementations

impl<K, T> FileBackedLfuCache<K, T>

where K: Key, T: AsyncFileRepr,

pub fn init( path: impl AsRef<Path>, capacity: usize, ) -> Result<Self, Error<K, T::Err>>

Initialise a cache with a specific capacity, using the given path as the backing directory.

The provided path must exist and resolve to a directory. Otherwise an error will be returned.

pub fn loaded_count(&self) -> usize

Get the number of loaded items in cache.

pub fn get_backing_directory(&self) -> &Path

Get the backing directory of this cache on disk.

pub fn get_path_for(&self, key: impl Borrow<K>) -> PathBuf

Get the file path in the backing directory for a key.

Note that this function does not care whether the input key exists or not, and therefore makes no guarantee on the existence of this file.

pub fn has_key(&self, key: impl Borrow<K>) -> bool

Get whether a key already exists, whether in cache or on disk.

pub fn has_loaded_key(&self, key: impl Borrow<K>) -> bool

Get whether a key has been loaded in cache.

pub fn has_flushed_key(&self, key: impl Borrow<K>) -> bool

Get whether a key has been flushed to disk.

pub fn get(&mut self, key: impl Borrow<K>) -> Result<Arc<T>, Error<K, T::Err>>

Get an item from cache (if present) using its unique key, and increment its usage frequency.

pub fn get_mut( &mut self, key: impl Borrow<K>, ) -> Result<&mut T, Error<K, T::Err>>

Get a mutable reference to an item from the cache using its unique key, and increment its usage frequency.

If there exists other Arcs that point to this item, this function will error because it’s not safe to mutate a shared value.

pub async fn get_or_load( &mut self, key: impl Borrow<K>, ) -> Result<Arc<T>, Error<K, T::Err>>

Using a unique key, get an item from cache, or if it is not found in cache, load it into cache first and then return it.

Usage frequency is incremented in both cases. Eviction will happen if necessary.

pub async fn get_or_load_mut( &mut self, key: impl Borrow<K>, ) -> Result<&mut T, Error<K, T::Err>>

Using a unique key, get a mutable reference to an item from cache, or if it not found in cache, load it into cache first and then return a mutable reference to it.

Usage frequency is incremented in both cases. Eviction will happen if necessary.

If there exists other Arcs that point to this item, this function will error because it’s not safe to mutate a shared value.

pub async fn push(&mut self, item: T) -> Result<K, Error<K, T::Err>>

Push an item into cache, assign it a unique key, then return the key.

Usage frequency is incremented. Eviction will happen if necessary.

Note that the newly added item will not be immediately flushed to the backing directory on disk.

pub async fn direct_flush(&self, item: T) -> Result<K, Error<K, T::Err>>

Directly flush an item into the backing directory on disk without touching the cache. Returns the assigned key.

Neither frequency increment nor eviction will not occur. Hence this method does not require a mutable reference to self.

pub async fn flush(&self, key: impl Borrow<K>) -> Result<(), Error<K, T::Err>>

Flush an item in cache to the backing directory on disk.

The flushed item neither has its frequency incremented, nor will it be evicted. Hence this method does not require a mutable reference to self.

pub async fn flush_all(&self) -> Result<(), Vec<Error<K, T::Err>>>

Flush all items in cache to the backing directory on disk.

The flushed items neither have their frequencies incremented, or are not evicted. Hence this method does not require a mutable reference to self.

Note that this method does not fail fast. Instead it makes a flush attempt on all items in cache, then collects and returns all errors encountered (if any). Therefore a partial failure is possible (and is likely).

pub async fn clear_cache( &mut self, do_flush: bool, ) -> Result<(), Vec<Error<K, T::Err>>>

Evict all items from cache, and optionally flushing all of them to the backing directory on disk.

pub async fn delete( &mut self, key: impl Borrow<K>, ) -> Result<(), Error<K, T::Err>>

Delete an item from both the cache and the backing directory on disk.

Trait Implementations

impl<K, T> Debug for FileBackedLfuCache<K, T>

where K: Key + Debug, T: AsyncFileRepr + Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.