Struct forceps::Cache

pub struct Cache { /* fields omitted */ }

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

This structure exposes read, write, and misc metadata operations. read and write are both async, whereas all metadata operations are sync. See CacheBuilder for all customization options.

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).

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))
}

Trait Implementations

impl Debug for Cache

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

Formats the value using the given formatter.