Crate forceps[−][src]

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
Tuned for large-file databases
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 forceps::Cache;

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

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

Structs

Cache	The main component of `forceps`, acts as the API for interacting with the on-disk API.
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`.