kingwingfly/rom-cache

rom-cache

A rust crate to cache ROM in memory like CPU caching RAM.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

Import
About The Project
- Built With
Usage
Changelog
Roadmap
Contributing
License
Contact
Acknowledgments

Import

[dependencies]
rom_cache = { version = "0.0.10" }

About The Project

A rust crate to cache ROM in memory like CPU caching RAM.

Trait Cacheable is provided to enable user define how to load and store data in Secondary Storage.

Cache is the main entry of this crate, which consists of CacheGroups. And CacheGroup consists of CacheLines.

Cache::get::<T>() and Cache::get_mut::<T>() are provided to retrieve data from Cache and storage. LRU is used to choose the CacheLine for T.

cache hit: return CacheRef
cache busy: CacheError::Busy, LRU-chosen CacheLine is still being writting or reading so that unable to be evicted.
cache locked: CacheError::Locked, cannot read T while writing.

get_mut

cache hit: return CacheMut, and dereferencing CacheMut will set CacheLine dirty.
cache busy: CacheError::Busy, cannot evict LRU-chosen CacheLine which is still being used.
cache locked: CacheError::Locked, cannot write T while reading or writing.

Any dirty CacheLine will be written back (Cacheable::store()) to Secondary Storage when evicted or Cache dropped.

Features

nightly: enable #![feature(trait_upcasting)] to simplify the Cacheable trait. (Nightly Rust is needed)

(back to top)

Built With

Rust
Miri (Testing)
Loom (Concurrency Testing)

(back to top)

Usage

Example

# use rom_cache::Cache;
// e.g 2-way set associative cache (8 sets/groups)
let cache: Cache<8, 2> = Default::default();
cache.get::<isize>().unwrap();
cache.get::<String>().unwrap();
{
    let mut s = cache.get_mut::<String>().unwrap();
    cache.get::<u64>().unwrap();
    cache.get::<usize>().unwrap();
    *s = "".to_string();    // set dirty
}
{
    let s = cache.get::<String>().unwrap(); // other threads may evict `String` and it's stored,
                                            // this will load it back
    assert_eq!(*s, "");                     // The `load` result is `""`
}

For more examples, please refer to the Tests, Example or Documentation

(back to top)

Changelog

todo

more detailed changelog

(back to top)

Roadmap

allow concurrent access
auto load when getting
benchmark

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!