pub struct Cache { /* private fields */ }Expand description
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§
Source§impl Cache
impl Cache
Sourcepub fn get<'a>(&self, key: impl Into<Key<'a>>) -> Result<Option<File>>
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.
Sourcepub fn ensure<'a>(
&self,
key: impl Into<Key<'a>>,
populate: impl FnOnce(&mut File) -> Result<()>,
) -> Result<File>
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. The populate
function can return ErrorKind::NotFound to skip the
comparison without failing the whole call.
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.
Sourcepub 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>
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. The populate
function can return ErrorKind::NotFound to skip the
comparison without failing the whole call.
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).
Sourcepub fn set<'a>(
&self,
key: impl Into<Key<'a>>,
value: impl AsRef<Path>,
) -> Result<()>
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.
Sourcepub fn set_temp_file<'a>(
&self,
key: impl Into<Key<'a>>,
value: NamedTempFile,
) -> Result<()>
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.
Sourcepub fn put<'a>(
&self,
key: impl Into<Key<'a>>,
value: impl AsRef<Path>,
) -> Result<()>
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.
Sourcepub fn put_temp_file<'a>(
&self,
key: impl Into<Key<'a>>,
value: NamedTempFile,
) -> Result<()>
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.
Sourcepub fn touch<'a>(&self, key: impl Into<Key<'a>>) -> Result<bool>
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.