Skip to content

Commit 4eac80b

Browse files
committed
tweak(docs): better README documentation
1 parent edf073c commit 4eac80b

File tree

2 files changed

+46
-18
lines changed

2 files changed

+46
-18
lines changed

README.md

Lines changed: 29 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,29 @@
1+
<div align="center">
2+
13
# Forceps
4+
[![docs.rs][docs-rs-badge]][docs-rs-url]
5+
[![crates.io][crates-badge]][crates-url]
6+
[![CI][ci-badge]][ci-url]
7+
8+
**The easy-to-use and asynchronous solution for your tokio project**
9+
10+
[docs-rs-badge]: https://docs.rs/forceps/badge.svg
11+
[docs-rs-url]: https://docs.rs/forceps/*/forceps
12+
[crates-badge]: https://img.shields.io/crates/v/forceps.svg
13+
[crates-url]: https://crates.io/crates/forceps
14+
[ci-badge]: https://github.com/blockba5her/forceps/actions/workflows/ci.yml/badge.svg
15+
[ci-url]: https://github.com/blockba5her/forceps/actions/workflows/ci.yml
16+
17+
<div>
18+
19+
---
220

3-
Forceps is a fast, asynchronous, and simple cache/database built for large-file storage for HTTP
4-
servers and other network applications. This crate is intended to be used with the `tokio`
5-
runtime.
21+
`forceps` is made to be an easy-to-use, thread-safe, performant, and asynchronous disk cache
22+
that has easy reading and manipulation of data. It levereges tokio's async `fs` APIs
23+
and fast task schedulers to perform IO operations, and `sled` as a fast metadata database.
624

7-
The motive behind this project is that there wasn't any good caching solutions for rust crates
8-
that were publically available. The best I found was zkat/cacache-rs, however it lacked in speed
9-
and wasn't what I was looking for exactly. This cache was specifically designed for
10-
[scalpel](https://github.com/blockba5her/scalpel), which is an image cache server for MangaDex.
25+
It was originally designed to be used in [`scalpel`](https://github.com/blockba5her/scalpel),
26+
the MD@Home implementation for the Rust language.
1127

1228
## Instability Warning
1329

@@ -23,12 +39,14 @@ It is advisable to use another solution if you have the option!
2339
- Optimized for cache `HIT`s
2440
- Easy error handling
2541

26-
### Features-to-come
42+
### Planned Features
2743

2844
- Toggleable in-memory LRU cache
29-
- Optional last-access timestamps
30-
- Removing database entries
31-
- Easy cache eviction
45+
- `bytes` crate support (planned non-optional)
46+
- Optional tracking of last-access timestamps
47+
- Removal of entries
48+
- Included cache eviction (LRU/FIFO)
49+
- Built-in cache integrity checks
3250

3351
## Documentation
3452

src/lib.rs

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,33 @@
11
//! `forceps` is a crate that provides a simple and easy-to-use on-disk cache/database.
22
//!
3-
//! **This crate is intended to be used with the [`tokio`] runtime.**
3+
//! **This crate is intended to be used with the [`tokio`](tokio) runtime.**
44
//!
5-
//! This crate is designed to be thread-safe, performant, and asyncronous for use in HTTP servers
6-
//! and other network applications. Because of it's use-case, it is optimized for workloads that
7-
//! include many cache `HIT`s as compared to `MISS`es.
5+
//! `forceps` is made to be an easy-to-use, thread-safe, performant, and asynchronous disk cache
6+
//! that has easy reading and manipulation of data. It levereges tokio's async `fs` APIs
7+
//! and fast task schedulers to perform IO operations, and `sled` as a fast metadata database.
88
//!
99
//! It was originally designed to be used in [`scalpel`](https://github.com/blockba5her/scalpel),
1010
//! the MD@Home implementation for the Rust language.
1111
//!
12-
//! # Features
12+
//! ## Features
1313
//!
1414
//! - Asynchronous APIs
1515
//! - Fast and reliable reading/writing
16-
//! - Tuned for large-file databases
16+
//! - Tuned for large-file-storage solutions
1717
//! - Easily accessible value metadata
18-
//! - Optimized for cache `HIT`s
18+
//! - Optimized for higher read ratio
1919
//! - Easy error handling
2020
//!
21+
//! ## Database and Meta-database
22+
//!
23+
//! This database solution easily separates data into two databases: the LFS (large-file-storage)
24+
//! database, and the metadata database. The LFS database is powered using Tokio's async filesystem
25+
//! operations, whereas the metadata database is powered using [`sled`](sled).
26+
//!
27+
//! The advantage of splitting these two up is simple: Accessing metadata (for things like database
28+
//! eviction) is realatively cheap and efficient, with the only downside being that `async` is not
29+
//! present.
30+
//!
2131
//! # Examples
2232
//!
2333
//! ```rust

0 commit comments

Comments
 (0)