Crate forceps

forceps is a crate that provides a simple and easy-to-use on-disk cache/database.

This crate is intended to be used with the tokio runtime.

forceps is made to be an easy-to-use, thread-safe, performant, and asynchronous disk cache that has easy reading and manipulation of data. It levereges tokio’s async fs APIs and fast task schedulers to perform IO operations, and sled as a fast metadata database.

It was originally designed to be used in scalpel, the MD@Home implementation for the Rust language.

Features

• Asynchronous APIs
• Fast and reliable reading/writing
• Optional memory-cache layer
• Tuned for large-file databases
• Included cache eviction (LRU/FIFO)
• Easily accessible value metadata
• Optimized for cache HITs
• Easy error handling
• bytes crate support (non-optional)

Database and Meta-database

This database solution easily separates data into two databases: the LFS (large-file-storage) database, and the metadata database. The LFS database is powered using Tokio’s async filesystem operations, whereas the metadata database is powered using sled.

The advantage of splitting these two up is simple: Accessing metadata (for things like database eviction) is realatively cheap and efficient, with the only downside being that async is not present.

Examples

use std::error::Error;
use forceps::Cache;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let cache = Cache::new("./cache")
        .build()
        .await?;

    cache.write(b"MY_KEY", b"Hello World").await?;
    let data = cache.read(b"MY_KEY").await?;
    assert_eq!(data.as_ref(), b"Hello World");

    Ok(())
}

Modules

evictors

A collection of Cache eviction algorithms and generics

Structs

Cache	The main component of forceps, and acts as the API for interacting with the on-disk cache.
CacheBuilder	A builder for the Cache object. Exposes APIs for configuring the initial setup of the database.
Metadata	Metadata information about a certain entry in the cache

Enums

ForcepError

Global error type for the forceps crate, which is used in the Result types of all calls to forcep APIs.

Type Definitions

Error	Re-export of ForcepError
Md5Bytes	Type definition for an array of bytes that make up an md5 hash.
Result	Result that is returned by all error-bound operations of forceps.