Expand description
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
HIT
s - 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
- A collection of
Cache
eviction algorithms and generics
Structs
- The main component of
forceps
, and acts as the API for interacting with the on-disk cache. - A builder for the
Cache
object. Exposes APIs for configuring the initial setup of the database. - Metadata information about a certain entry in the cache
Enums
- Global error type for the
forceps
crate, which is used in theResult
types of all calls to forcep APIs.
Type Aliases
- Re-export of
ForcepError
- Type definition for an array of bytes that make up an
md5
hash. - Result that is returned by all error-bound operations of
forceps
.