Lib.rs

Import

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

About The Project

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

(Here, ROM is a misnomer, it actually means data stored in Secondary Storage, e.g. HDD, SSD, etc.)

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.

1. get

• 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.

2. 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), 16 cache lines in total
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!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Contact

Louis - 836250617@qq.com

Project Link: https://github.com/kingwingfly/rom-cache

(back to top)