Struct kismet_cache::Cache

pub struct Cache { /* fields omitted */ }

A Cache wraps either up to one plain or sharded read-write cache in a convenient interface, and may optionally fulfill read operations by deferring to a list of read-only cache when the read-write cache misses.

The default cache has no write-side and an empty stack of backup read-only caches.

Cache objects are cheap to clone and lock-free; don’t put an Arc on them. Avoid opening multiple caches for the same set of directories: using the same Cache object improves the accuracy of the write cache’s lock-free in-memory statistics, when it’s a sharded cache.

Implementations

impl Cache

pub fn get<'a>(&self, key: impl Into<Key<'a>>) -> Result<Option<File>>

Attempts to open a read-only file for key. The Cache will query each its write cache (if any), followed by the list of additional read-only cache, in definition order, and return a read-only file for the first hit.

Fails with ErrorKind::InvalidInput if key.name is invalid (empty, or starts with a dot or a forward or back slash).

Returns None if no file for key can be found in any of the constituent caches, and bubbles up the first I/O error encountered, if any.

In the worst case, each call to get attempts to open two files for the Cache’s read-write directory and for each read-only backup directory.

pub fn ensure<'a>(
    &self,
    key: impl Into<Key<'a>>,
    populate: impl FnOnce(&mut File) -> Result<()>
) -> Result<File>

Attempts to find a cache entry for key. If there is none, populates the cache with a file filled by populate. Returns a file in all cases (unless the call fails with an error).

Always invokes populate for a consistency check when a consistency check function is provided.

Fails with ErrorKind::InvalidInput if key.name is invalid (empty, or starts with a dot or a forward or back slash).

See Cache::get_or_update for more control over the operation.

pub fn get_or_update<'a>(
    &self,
    key: impl Into<Key<'a>>,
    judge: impl FnOnce(CacheHit<'_>) -> CacheHitAction,
    populate: impl FnOnce(&mut File, Option<File>) -> Result<()>
) -> Result<File>

Attempts to find a cache entry for key. If there is none, populates the write cache (if possible) with a file, once filled by populate; otherwise obeys the value returned by judge to determine what to do with the hit.

Always invokes populate for a consistency check when a consistency check function is provided.

Fails with ErrorKind::InvalidInput if key.name is invalid (empty, or starts with a dot or a forward or back slash).

When we need to populate a new file, populate is called with a mutable reference to the destination file, and the old cached file (in whatever state judge left it), if available.

See Cache::ensure for a simpler interface.

In the worst case, each call to get_or_update attempts to open two files for the Cache’s read-write directory and for each read-only backup directory, and fails to find anything. get_or_update then publishes a new cached file (in a constant number of file operations), but not before triggering a second chance maintenance (time linearithmic in the number of files in the directory chosen for maintenance, but amortised to logarithmic).

pub fn set<'a>(
    &self,
    key: impl Into<Key<'a>>,
    value: impl AsRef<Path>
) -> Result<()>

Inserts or overwrites the file at value as key in the write cache directory. This will always fail with ErrorKind::Unsupported if no write cache was defined. The path at value must be in the same filesystem as the write cache directory: we rely on atomic file renames.

Fails with ErrorKind::InvalidInput if key.name is invalid (empty, or starts with a dot or a forward or back slash).

Always consumes the file at value on success; may consume it on error.

When auto_sync is enabled (the default), the file at value will always be File::sync_alled before publishing to the cache. Kismet will panic when the File::sync_all call itself fails: retrying the same call to Cache::set could erroneously succeed, since some filesystems clear internal I/O failure flag after the first fsync.

Executes in a bounded number of file operations, except for the lock-free maintenance, which needs time linearithmic in the number of files in the directory chosen for maintenance, amortised to logarithmic, and constant number of file operations.

pub fn set_temp_file<'a>(
    &self,
    key: impl Into<Key<'a>>,
    value: NamedTempFile
) -> Result<()>

Invokes Cache::set on a tempfile::NamedTempFile.

See Cache::set for more details. The only difference is that set_temp_file does not panic when auto_sync is enabled and we fail to File::sync_all the NamedTempFile value.

pub fn put<'a>(
    &self,
    key: impl Into<Key<'a>>,
    value: impl AsRef<Path>
) -> Result<()>

Inserts the file at value as key in the cache directory if there is no such cached entry already, or touches the cached file if it already exists. This will always fail with ErrorKind::Unsupported if no write cache was defined. The path at value must be in the same filesystem as the write cache directory: we rely on atomic file hard linkage.

Fails with ErrorKind::InvalidInput if key.name is invalid (empty, or starts with a dot or a forward or back slash).

Always consumes the file at value on success; may consume it on error.

When auto_sync is enabled (the default), the file at value will always be File::sync_alled before publishing to the cache. Kismet will panic when the File::sync_all call itself fails: retrying the same call to Cache::put could erroneously succeed, since some filesystems clear internal I/O failure flag after the first fsync.

Executes in a bounded number of file operations, except for the lock-free maintenance, which needs time linearithmic in the number of files in the directory chosen for maintenance, amortised to logarithmic, and constant number of file operations.

pub fn put_temp_file<'a>(
    &self,
    key: impl Into<Key<'a>>,
    value: NamedTempFile
) -> Result<()>

Invokes Cache::put on a tempfile::NamedTempFile.

See Cache::put for more details. The only difference is that put_temp_file does not panic when auto_sync is enabled and we fail to File::sync_all the NamedTempFile value.

pub fn touch<'a>(&self, key: impl Into<Key<'a>>) -> Result<bool>

Marks a cache entry for key as accessed (read). The Cache will touch the same file that would be returned by get.

Fails with ErrorKind::InvalidInput if key.name is invalid (empty, or starts with a dot or a forward or back slash).

Returns whether a file for key could be found, and bubbles up the first I/O error encountered, if any.

In the worst case, each call to touch attempts to update the access time on two files for each cache directory in the ReadOnlyCache stack.

Trait Implementations

impl Clone for Cache

fn clone(&self) -> Cache

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Cache

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

Formats the value using the given formatter.

impl Default for Cache

fn default() -> Cache

Returns the “default value” for a type.