pub struct Cache(/* private fields */);Implementations§
Source§impl Cache
impl Cache
Sourcepub fn new_lru_cache(capacity: size_t) -> Cache
pub fn new_lru_cache(capacity: size_t) -> Cache
Creates an LRU cache with capacity in bytes.
Sourcepub fn new_lru_cache_opts(opts: &LruCacheOptions) -> Cache
pub fn new_lru_cache_opts(opts: &LruCacheOptions) -> Cache
Creates an LRU cache with custom options.
Sourcepub fn new_lru_cache_with_strict_capacity_limit(capacity: size_t) -> Cache
pub fn new_lru_cache_with_strict_capacity_limit(capacity: size_t) -> Cache
Creates an LRU cache with capacity in bytes that refuses to exceed it.
A normal LRU cache treats the capacity as a target. When an insert
arrives and nothing more can be evicted, because the remaining entries
are pinned, it inserts anyway and lets usage go over capacity. With the
strict limit the insert fails with MemoryLimit instead, so the cache
is a hard memory bound.
That failure is not confined to the cache API. RocksDB inserts into the
block cache while reading, so operations that need a block the cache
cannot hold surface the error to the caller. Opening a table file can
fail the same way when
BlockBasedOptions::set_cache_index_and_filter_blocks charges the
reader against a full cache. Size the cache with headroom before
turning this on.
Sourcepub fn new_hyper_clock_cache(
capacity: size_t,
estimated_entry_charge: size_t,
) -> Cache
pub fn new_hyper_clock_cache( capacity: size_t, estimated_entry_charge: size_t, ) -> Cache
Creates a HyperClockCache with capacity in bytes.
HyperClockCache is now generally recommended over LRUCache. See RocksDB’s HyperClockCacheOptions in cache.h for details.
estimated_entry_charge is an optional parameter. When not provided
(== 0, recommended and default), an HCC variant with a
dynamically-growing table and generally good performance is used. This
variant depends on anonymous mmaps so might not be available on all
platforms.
If the average “charge” (uncompressed block size) of block cache entries
is reasonably predicted and provided here, the most efficient variant of
HCC is used. Performance is degraded if the prediction is inaccurate.
Prediction could be difficult or impossible with cache-charging features
such as WriteBufferManager. The best parameter choice based on a cache
in use is roughly given by cache.get_usage() / cache.get_occupancy_count(),
though it is better to estimate toward the lower side than the higher
side when the ratio might vary.
Sourcepub fn new_hyper_clock_cache_opts(opts: &HyperClockCacheOptions) -> Cache
pub fn new_hyper_clock_cache_opts(opts: &HyperClockCacheOptions) -> Cache
Creates a HyperClockCache with custom options.
Use this over Self::new_hyper_clock_cache to set the shard count or
a memory allocator. See HyperClockCacheOptions.
Sourcepub fn get_pinned_usage(&self) -> usize
pub fn get_pinned_usage(&self) -> usize
Returns the pinned memory usage in bytes.
Sourcepub fn get_capacity(&self) -> usize
pub fn get_capacity(&self) -> usize
Returns the configured cache capacity in bytes.
Sourcepub fn get_occupancy_count(&self) -> usize
pub fn get_occupancy_count(&self) -> usize
Returns the number of entries currently occupying the cache hash tables.
Sourcepub fn get_table_address_count(&self) -> usize
pub fn get_table_address_count(&self) -> usize
Returns the total number of cache hash table addresses.
Sourcepub fn set_capacity(&mut self, capacity: size_t)
pub fn set_capacity(&mut self, capacity: size_t)
Sets cache capacity in bytes.
Sourcepub unsafe fn disown_data(&mut self)
pub unsafe fn disown_data(&mut self)
Give up the cached data instead of freeing it when the cache goes away.
This is RocksDB’s Cache::DisownData. It only changes what happens at
destruction: the last drop stops running the shard destructors, so the
cached entries are never reclaimed. It exists to make process exit
faster on a large cache, where walking and freeing every entry costs
real time and nothing is going to reuse the memory anyway.
Cache is a reference-counted handle, so this affects the shared cache
and every other clone of it, not just this handle.
Under ASAN or valgrind RocksDB ignores the request and frees the entries as usual, so the leak is not reported there.
§Safety
Every database and every other user of this cache must be dropped
before this call — RocksDB’s contract is: “Always delete the DB object
before calling this method!” (advanced_cache.h). Nothing may read
from or write to the cache after this call; RocksDB documents any use
after disowning as unsupported. Anything that would have reused the
memory later cannot, because it is leaked for the remaining lifetime of
the process, which makes this call worth doing only shortly before the
process exits.