Crate forceps 

forceps is a simple and easy-to-use on-disk cache/database for large files.

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.

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 Aliases

Error

Re-export of ForcepError

HashBytes

Type definition for an array of bytes that make up an 16-byte hash (e.g., md5, xx3, etc.).

Result

Result that is returned by all error-bound operations of forceps.