15536afe8d
This PR is based on the work @alexschrod did in PR #29. All I did was carry it over the finish line. This PR adds a feature to the crate named `tokio-runtime`. If you disable default features and enable this new one, cacache uses tokio as its async executor. This makes integrating cacache with tokio-using projects easier, because the file types leak out if you use anything more than the top-level convenience functions. The PR implements the feature using shims in a new submodule named `async_lib`. This module conditionally uses either async-std or tokio based on feature selection, and hides some differences with convenience functions. This change should not be a breaking change, because the default is still async-std. There are a few other small changes in this PR worth noting. - The README shows how to switch runtimes. - There's a justfile to run common tasks, including those in makefile.toml. The default shell is `sh`, so this might not work out of the box for Windows users. - The tests can now run under either runtime. The justfile has a recipe that runs them both. - The benchmarks can also run under either runtime. The justfile has two recipe for this, one using bench and the other using criterion's runner. - The dependencies now pull in async-attributes by default along with async-std. This made it easier to swap runtimes in the tests. - All dependency versions have been bumped. Co-authored-by: @alexschrod |
||
|---|---|---|
| .github | ||
| benches | ||
| src | ||
| .gitignore | ||
| CHANGELOG.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| Cargo.toml | ||
| LICENSE.md | ||
| Makefile.toml | ||
| README.md | ||
| cliff.toml | ||
| justfile | ||
README.md
cacache 
A high-performance, concurrent, content-addressable disk cache, optimized for async APIs.
Example
use cacache;
use async_attributes;
#[async_attributes::main]
async fn main() -> Result<(), cacache::Error> {
let dir = String::from("./my-cache");
// Write some data!
cacache::write(&dir, "key", b"my-async-data").await?;
// Get the data back!
let data = cacache::read(&dir, "key").await?;
assert_eq!(data, b"my-async-data");
// Clean up the data!
cacache::rm::all(&dir).await?;
}
Install
Using cargo-edit
$ cargo add cacache
Minimum supported Rust version is 1.43.0.
Documentation
Features
- First-class async support, using either
async-stdortokioas its runtime. Sync APIs are available but secondary std::fs-style API- Extraction by key or by content address (shasum, etc)
- Subresource Integrity web standard support
- Multi-hash support - safely host sha1, sha512, etc, in a single cache
- Automatic content deduplication
- Atomic content writes even for large data
- Fault tolerance (immune to corruption, partial writes, process races, etc)
- Consistency guarantees on read and write (full data verification)
- Lockless, high-concurrency cache access
- Really helpful, contextual error messages
- Large file support
- Pretty darn fast
- Arbitrary metadata storage
- Cross-platform: Windows and case-(in)sensitive filesystem support
- Punches nazis
async-std is the default async runtime. To use tokio instead, turn off default features and enable the tokio-runtime feature, like this:
[dependencies]
cacache = { version = "*", default-features = false, features = ["tokio-runtime"] }
Contributing
The cacache team enthusiastically welcomes contributions and project participation! There's a bunch of things you can do if you want to contribute! The Contributor Guide has all the information you need for everything from reporting bugs to contributing entire new features. Please don't hesitate to jump in if you'd like to, or even ask us questions if something isn't clear.
All participants and maintainers in this project are expected to follow Code of Conduct, and just generally be excellent to each other.
Happy hacking!
License
This project is licensed under the Apache-2.0 License.