Struct DirCache 

pub struct DirCache { /* private fields */ }

A directory-based cache with a map-like interface.

Example

use std::convert::Infallible;
use std::path::Path;
use dir_cache::opts::{CacheOpenOptions, DirCacheOpts, DirOpenOpt};
fn use_cache() {
    let temp = tempfile::TempDir::with_prefix("dir-cache-doc-test").unwrap();
    let mut dir_cache = DirCacheOpts::default()
        .open(temp.path(), CacheOpenOptions::new(DirOpenOpt::OnlyIfExists, false)).unwrap();

    // Be careful about paths used, these are joined onto the base directory and
    // should ideally not be dynamic
    let slow_value_key = Path::new("slow-key");
    // Will only execute the closure if the value is not present.
    let value = dir_cache.get_or_insert(slow_value_key, || Ok::<_, Infallible>(b"My hard to get value".to_vec())).unwrap();
    assert_eq!(b"My hard to get value".as_slice(), value.as_ref());
}

Implementations

impl DirCache

pub fn opts(&self) -> &DirCacheOpts

Get this DirCache’s DirCacheOpts. To change one opt for an operation, for example.

pub fn get(&mut self, key: &Path) -> Result<Option<Cow<'_, [u8]>>>

Get the value of a key using this DirCache’s options. Returns Option::None if the key isn’t stored in the cache. If the key is stored in the cache it will be retrieved either from memory or disk. The value will be owned only if MemPullOpt::DontKeepInMemoryOnRead is specified which is why the return value is a Cow<_>

Errors

Various io-errors reading and managing disk state

pub fn get_opt( &mut self, key: &Path, opts: DirCacheOpts, ) -> Result<Option<Cow<'_, [u8]>>>

Same as DirCache::get but with opts other than what the DirCache was instantiated with.

Errors

Same as DirCache::get

pub fn get_or_insert<E: Into<Box<dyn Error>>, F: FnOnce() -> Result<Vec<u8>, E>>( &mut self, key: &Path, insert_with: F, ) -> Result<Cow<'_, [u8]>>

Get a key if it exists and is valid according to GenerationOpt, otherwise use the provided insert_with function to generate and insert a key. The return value is a Cow<_> which is borrowed if MemPushOpt::MemoryOnly or MemPushOpt::RetainAndWrite is specified, or owned otherwise.

Errors

Accepts a fallible function which can fail, in which case that function’s converted error is returned wrapped. May also perform disk-operations based on opts, which may fail. Additionally, will fail on paths that are not safe to use with DirCache

pub fn get_or_insert_opt<E: Into<Box<dyn Error>>, F: FnOnce() -> Result<Vec<u8>, E>>( &mut self, key: &Path, insert_with: F, opts: DirCacheOpts, ) -> Result<Cow<'_, [u8]>>

Same as DirCache::get_or_insert but with DirCacheOpts different from what this DirCache was instantiated with.

Errors

Same as DirCache::get_or_insert

pub fn insert(&mut self, key: &Path, content: Vec<u8>) -> Result<()>

Insert content as a value for the provided key into this DirCache. Will result in direct writes to disk if MemPushOpt::MemoryOnly isn’t used. If MemPushOpt::MemoryOnly isn’t used and GenerationOpt specifies more than one generation, a new generation will be written to disk, and previous generations will age.

Errors

Will error on using a key that’s not safe to use with DirCache. May error on various io-errors relating to writing to disk.

pub fn insert_opt( &mut self, key: &Path, content: Vec<u8>, opts: DirCacheOpts, ) -> Result<()>

Insert content as a value for the provided key using the specified opts instead of the DirCacheOpts that this DirCache was instantiated with, otherwise same as DirCache::insert.

Errors

Same as DirCache::insert

pub fn remove(&mut self, key: &Path) -> Result<bool>

Removes a key from the map, and cleans up the state left on disk.

Errors

Various io-errors relating to probing and deleting content from disk

pub fn sync(&mut self) -> Result<()>

Sync in-memory written content to disk, same as DirCache::sync. If SyncOpt::ManualSync and MemPushOpt::MemoryOnly are both enabled, calling this method is the only way to flush map-state to disk.

Errors

Various io-errors related to writing to disk

pub fn sync_opt(&mut self, opts: DirCacheOpts) -> Result<()>

Sync in-memory written content to disk, same as DirCache::sync but with options different to those this DirCache was instantiated with.

Errors

Same as DirCache::sync

Trait Implementations

impl Drop for DirCache

fn drop(&mut self)

Executes the destructor for this type.