# DiskLRU
[DiskLRU](https://gitlab.com/liberecofr/disklru) is an experimental LRU store implemented in [Rust](https://www.rust-lang.org/).
It works as a simple key-value store and is powered by [sled](https://crates.io/crates/sled/)
which is _a lightweight pure-rust high-performance transactional embedded database_.
It expires entries automatically passed a given number, following the LRU (least recently used) strategy,
which is a quite [common cache replacement policy]( https://en.wikipedia.org/wiki/Cache_replacement_policies).
It comes with a cost but is sometimes more adapted than just expiring the old keys in FIFO mode (first-in, first-out)
as you may have a key-value pair which has been introduced a very long time ago in the store,
but is still relevant. With DiskLRU, if your code is reading the value often, it will ensure
the key stays alive and does not disappear.
* [HashLRU](https://gitlab.com/liberecofr/hashlru) is very similar in its design, and acts
as an in-memory cache, as opposed to DiskLRU being a persistent store.
* [MenhirKV](https://gitlab.com/liberecofr/menhirkv) solves the same problem that DiskLRU addresses,
which is "store stuff, keep most used value at hand, drop the rest". It does it in a less pedantic
and precise way, but much more efficiently.
# Status
For now this is a toy project, clearly *NOT* suitable for production use.
[](https://gitlab.com/liberecofr/disklru/pipelines)
Here is a quick bench done on a 100k items store:
```
running 8 tests
test tests::bench_read_usize_disklru ... bench: 18,179 ns/iter (+/- 16,489)
test tests::bench_read_usize_hashlru ... bench: 39 ns/iter (+/- 4)
test tests::bench_read_usize_hashmap ... bench: 13 ns/iter (+/- 0)
test tests::bench_read_usize_lru ... bench: 9 ns/iter (+/- 0)
test tests::bench_write_usize_disklru ... bench: 34,290 ns/iter (+/- 26,546)
test tests::bench_write_usize_hashlru ... bench: 104 ns/iter (+/- 15)
test tests::bench_write_usize_hashmap ... bench: 67 ns/iter (+/- 13)
test tests::bench_write_usize_lru ... bench: 22 ns/iter (+/- 5)
test result: ok. 0 passed; 0 failed; 0 ignored; 8 measured; 0 filtered out; finished in 30.12s
```
Those results are not super reliable, just a one-shot test ran on a laptop.
However there is a tendency: `disklru` is way slower than any real non-persistent
in-memory cache, and it has a high variability in results, very likely due to
the fact some flushes must happen somewhere in the process, acting as outliers.
# Usage
```rust
use disklru::Store;
let mut store = Store::open_temporary(4).unwrap();
store.insert(&1, &10).unwrap();
store.insert(&2, &20).unwrap();
store.insert(&3, &30).unwrap();
store.insert(&4, &40).unwrap();
store.insert(&5, &50).unwrap();
// key1 has been dropped, size is limited to 4
assert_eq!(Some(2), store.lru().unwrap());
assert_eq!(Some(20), store.get(&2).unwrap());
// getting key2 has made key3 the least recently used item
assert_eq!(Some(3), store.lru().unwrap());
assert_eq!(Some(40), store.get(&4).unwrap());
// getting key4 makes it the most recently used item
assert_eq!("[3: 30, 5: 50, 2: 20, 4: 40]", format!("{}", store));
store.flush().unwrap(); // commit
```
# Links
* [crate](https://crates.io/crates/disklru) on crates.io
* [doc](https://docs.rs/disklru/) on docs.rs
* [source](https://gitlab.com/liberecofr/disklru/tree/main) on gitlab.com
* [sled](https://github.com/spacejam/sled), the database powering this LRU store
* [HashLRU](https://gitlab.com/liberecofr/disklru), a similar in-memory cache
* [MenhirKV](https://gitlab.com/liberecofr/menhirkv), recommended alternative
# License
DiskLRU is licensed under the [MIT](https://gitlab.com/liberecofr/disklru/blob/main/LICENSE) license.
