Struct Cache

pub struct Cache { /* private fields */ }

The main component of forceps, and acts as the API for interacting with the on-disk cache.

This structure includes the async read, write, and remove operations which are the basic operations of the cache. It also includes some misc functions to interact with metadata and evict items from the cache.

Eviction

This cache can evict items with a number of different eviction algorithms. To see more, see evict_with and the evictors module.

Memory Cache

An in-memory cache can be optionally enabled as a layer over the regular on-disk cache. The memcache provides fast HITs for recently used entries, circumventing filesystem operations altogether. To enable, use the CacheBuilder::memory_lru_max_size method.

Examples

use forceps::Cache;

let cache = Cache::new("./cache")
    .build()
    .await
    .unwrap();

Implementations

impl Cache

pub fn new<P: AsRef<Path>>(path: P) -> CacheBuilder

Creates a new CacheBuilder, which can be used to customize and create a Cache instance. This function is an alias for CacheBuilder::new.

The path supplied is the base directory of the cache instance.

Examples

use forceps::Cache;

let builder = Cache::new("./cache");
// Use other methods for configuration

pub async fn read<K: AsRef<[u8]>>(&self, key: K) -> Result<Bytes>

Reads an entry from the database, returning a vector of bytes that represent the entry.

Not Found

If the entry is not found, then it will return Err(Error::NotFound).

Metadata

This function will not perform a metadata read or write unless the track_access build option is set. If the option is set, then it will perform a blocking read/write to write new values to track the last access time and the total hits.

Examples

use forceps::Cache;

let cache = Cache::new("./cache")
    .build()
    .await
    .unwrap();

let value = cache.read(b"MY_KEY").await.unwrap();
assert_eq!(value.as_ref(), b"Hello World");

pub async fn write<K: AsRef<[u8]>, V: AsRef<[u8]>>( &self, key: K, value: V, ) -> Result<Metadata>

Writes an entry with the specified key to the cache database. This will replace the previous entry if it exists, otherwise it will store a completely new one.

Examples

use forceps::Cache;

let cache = Cache::new("./cache")
    .build()
    .await
    .unwrap();

cache.write(b"MY_KEY", b"Hello World").await.unwrap();

pub async fn remove<K: AsRef<[u8]>>(&self, key: K) -> Result<Metadata>

Removes an entry from the cache, returning its Metadata.

This will remove the entry from both the main cache database and the metadata database. Please note that this will return Error::NotFound if either the main database or the meta database didn’t find the entry.

Examples

use forceps::Cache;

let cache = Cache::new("./cache")
    .build()
    .await
    .unwrap();

let metadata = cache.remove(b"MY_KEY").await.unwrap();
assert_eq!(metadata.get_size(), b"Hello World".len() as u64);

pub fn read_metadata<K: AsRef<[u8]>>(&self, key: K) -> Result<Metadata>

Queries the index database for metadata on the entry with the corresponding key.

This will return the metadata for the associated key. For information about what metadata is stored, look at Metadata.

Non-Async

Note that this function is not an async call. This is because the backend database used, sled, is not async-compatible. However, these calls are instead very fast.

Not Found

If the entry is not found, then it will return Err(Error::NotFound).

Examples

use forceps::Cache;

let cache = Cache::new("./cache")
    .build()
    .await
    .unwrap();

let meta = cache.read_metadata(b"MY_KEY").unwrap();
assert_eq!(meta.get_size(), b"Hello World".len() as u64);

pub fn metadata_iter(&self) -> impl Iterator<Item = Result<(Vec<u8>, Metadata)>>

An iterator over the entire metadata database, which provides metadata for every entry.

This iterator provides every key in the database and the associated metadata for that key. This is not an iterator over the actual values of the database.

Non-Async

Note that this function is not an async call. This is because the backend database used, sled, is not async-compatible. However, these calls are instead very fast.

Examples

use forceps::Cache;

let cache = Cache::new("./cache")
    .build()
    .await
    .unwrap();

for result in cache.metadata_iter() {
    let (key, meta) = result.unwrap();
    println!("{}", String::from_utf8_lossy(&key))
}

pub async fn evict_with<E>(&self, evictor: E) -> Result<u64, E::Err>

where E: Evictor,

Runs the specified eviction algorithm over this instance cache instance.

Eviction algorithms will remove items out of the cache until certain a condition has been met, usually a size requirement. See the evictors module for more information and examples.

Trait Implementations

impl Debug for Cache

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

Formats the value using the given formatter.