rom_cache 0.0.4

Cache ROM in memory like CPU caching RAM.
Documentation

Contributors Forks Stargazers Issues MIT License

Import

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

About The Project

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

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

get and get_mut will lock the CacheGroup, then load and upgrade LRU.

  1. get (RwLockReadGuard)
  • cache hit: return CacheRef from cache.
  • cache busy: CacheError::Busy, cannot evict LRU-chosen CacheLine since being used.
  • cache locked: CacheError::Locked, cannot get read-lock while writing.
  1. get_mut (RwLockWriteGuard)
  • cache hit: return CacheMut from cache, and dereference CacheMut will set CacheLine dirty.
  • cache busy: CacheError::Busy, cannot evict LRU-chosen CacheLine since being used.
  • cache locked: CacheError::Locked, cannot get write-lock while reading or writing.

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

Features

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

Built With

  • Rust
  • Miri (Testing)
  • Loom (Concurrency Testing)

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

Changelog

todo

more detailed changelog

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

License

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

Contact

Louis - 836250617@qq.com

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