[−][src]Crate moka
Moka is (aiming to be) a fast, concurrent cache library for Rust. Moka is inspired by Caffeine (Java) and Ristretto (Go).
This crate provides in-memory concurrent cache implementations
Cache
and SegmentedCache
.
They support full concurrency of retrievals and a high expected
concurrency for updates.
Both Cache
and SegmentedCache
utilize a lock-free concurrent
hash table cht::SegmentedHashMap
from the cht crate
for the central key-value storage. These caches perform a
best-effort bounding of a map using an entry replacement algorithm
to determine which entries to evict when the capacity is exceeded.
While Cache
will be good for general use cases, SegmentedCache
may yield better performance under heavy concurrent updates.
However, SegmentedCache
has little overheads on
retrievals/updates for managing multiple internal segments.
Status
Moka is currently in a very early stage of development (design and PoC). Many features are not implemented and the API will change very often.
Example
TODO
Concurrency
The entry replacement algorithms are kept eventually consistent with the map. While updates to the cache are immediately applied to the map, recording of reads and writes may not be immediately reflected on the cache policy's data structures.
These structures are guarded by a lock and operations are applied in batches to avoid lock contention. There are bounded inter-thread channels to hold these operations. These channels are drained at the first opportunity when:
- The numbers of read/write recordings reach to the configured amounts.
- Or, the certain time past from the last draining.
In a Cache
, this draining and batch application is handled by a
single worker thread. So under heavy concurrent operations from
clients, draining may not be able to catch up and the bounded
channels can become full.
When read or write channel becomes full, one of the followings will occur:
- For the read channel, recordings of new reads will be discarded, so that retrievals will never be blocked. This behavior may have some impact to the hit rate of the cache.
- For the write channel, updates from clients to the cache will be blocked until the draining task catches up.
Cache
does its best to avoid blocking updates by adjusting the
interval of draining and throttling updates from clients. But
since it has only one worker thread, it cannot always avoid
blocking. If this happens very often in your cache (in the future,
you can check the statistics of the cache), you may want to
switch to SegmentedCache
. It has multiple internal cache
segments and each segment has dedicated draining thread.
Admission and Eviction
Every time a client tries to retrieve an item from the cache, that activity is retained in a historic popularity estimator. This estimator has a tiny memory footprint as it uses hashing to probabilistically estimate an item's frequency.
Both Cache
and SegmentedCache
employ TinyLFU (Least
Frequently Used) as the admission policy. When a new entry is
inserted to the cache, it is temporary admitted to the cache, and
a recording of this insertion is added to the write queue. When
the write queue is drained and the main space of the cache is
already full, then the historic popularity estimator determines to
evict one of the following entries:
- The newly admitted entry
- Or, the victim entry that is selected from the main space by LRU (Least Recently Used) eviction policy
In a future release of this crate, TinyLFU admission policy will be replaced by Window TinyLFU (W-TinyLFU) policy. W-TinyLFU has an admission window in front of the main space. A new entry starts in the admission window and remains there as long as it has high temporal locality (recency). Eventually an entry will slip off from the window, then TinyLFU comes in play to determine whether or not to admit the entry to the main space based on its popularity (frequency).
Expiration
Cache expiration policies such as time-to-live are planned but not implemented in the current release of this crate.
A future release will provide such policies with O(1) time complexity:
- The time-to-live policy will use a write-order queue.
- The time-to-idle policy will use an access-order queue.
- The variable expiration will use a hierarchical timer wheel.
Structs
Cache | |
SegmentedCache |
Traits
ConcurrentCache |