#include <userver/cache/nway_lru_cache.hpp>

Detailed Description

template<typename T, typename U, typename Hash = std::hash<T>, typename Equal = std::equal_to<T>>
class cache::NWayLRU< T, U, Hash, Equal >

N-way LRU cache with per-way mutexes and optional dump support.

    cache::NWayLRU<int, std::string> cache(1, 1);
    EXPECT_EQ(0, cache.GetSize());
 
    cache.Put(1, "1");
    EXPECT_EQ(1, cache.GetSize());
 
    cache.Put(2, "2");
    EXPECT_EQ("2", cache.Get(2));
    EXPECT_EQ(1, cache.GetSize());
    EXPECT_FALSE(cache.Get(1).has_value());

Definition at line 23 of file nway_lru_cache.hpp.

Public Member Functions
	NWayLRU (size_t ways, size_t way_size, const Hash &hash=Hash(), const Equal &equal=Equal())
	Constructs an N-way LRU cache with the given number of ways and maximum elements per way.

void	Put (const T &key, U value)
	Stores value by key.

template<typename Validator>
std::optional< U >	Get (const T &key, Validator validator)
	Returns cached value by key if validator returns true for it.

std::optional< U >	Get (const T &key)
	Returns cached value by key if present; otherwise std::nullopt.

U	GetOr (const T &key, const U &default_value)
	Returns cached value by key if present; otherwise returns default_value.

void	Invalidate ()
	Removes all entries from the cache.

void	InvalidateByKey (const T &key)
	Removes the entry for the given key if present.

template<typename Function>
void	VisitAll (Function func) const
	Iterates over all items, invoking `func` for each (key, value).

size_t	GetSize () const
	Returns the total number of elements in the cache across all ways.

void	UpdateWaySize (size_t way_size)
	Updates maximum elements per way.

void	Write (dump::Writer &writer) const
	Serializes the cache contents to the dump writer.

void	Read (dump::Reader &reader)
	Deserializes the cache contents from the dump reader.

void	SetDumper (std::shared_ptr< dump::Dumper > dumper)
	Sets the dumper; it will be notified of any cache updates.

Constructor & Destructor Documentation

◆ NWayLRU()

template<typename T, typename U, typename Hash = std::hash<T>, typename Equal = std::equal_to<T>>

cache::NWayLRU< T, U, Hash, Eq >::NWayLRU	(	size_t	ways,
		size_t	way_size,
		const Hash &	hash = Hash(),
		const Equal &	equal = Equal() )

Constructs an N-way LRU cache with the given number of ways and maximum elements per way.

The maximum total number of elements is ways * way_size.

Parameters

ways	Number of ways (a.k.a. shards, internal hash-maps), into which elements are distributed based on their hash. Each shard is protected by an individual mutex. Larger `ways` means more internal hash-map instances and more memory usage, but less contention. A good starting point is `ways=16`. If you encounter contention, you can increase `ways` to something on the order of `256` or whatever your RAM constraints allow.
way_size	Maximum allowed amount of elements per way. When the size of a way reaches this number, existing elements are deleted according to the LRU policy.
hash	Instance of `Hash` function to use, in case of a custom stateful Hash.
equal	Instance of `Equal` function to use, in case of a custom stateful Equal.

Exceptions

std::logic_error if ways is zero.

Definition at line 136 of file nway_lru_cache.hpp.

Member Function Documentation

◆ Get() [1/2]

template<typename T, typename U, typename Hash = std::hash<T>, typename Equal = std::equal_to<T>>

std::optional< U > cache::NWayLRU< T, U, Hash, Equal >::Get ( const T & key )

inline

Returns cached value by key if present; otherwise std::nullopt.

Parameters

key	Key to look up.

Returns: Cached value if present, otherwise std::nullopt.

Note: Equivalent to Get(key, [](const U&) { return true; }).

Definition at line 66 of file nway_lru_cache.hpp.

◆ Get() [2/2]

template<typename T, typename U, typename Hash, typename Eq>

template<typename Validator>

std::optional< U > cache::NWayLRU< T, U, Hash, Eq >::Get	(	const T &	key,
		Validator	validator )

Returns cached value by key if validator returns true for it.

Parameters

key	Key to look up.
validator	Callable that takes the cached value and returns false to invalidate the entry.

Returns: Cached value if present and validator returned true, otherwise std::nullopt.

Note: If validator returns false, the entry is removed from the cache.

Definition at line 165 of file nway_lru_cache.hpp.

◆ GetOr()

template<typename T, typename U, typename Hash, typename Eq>

U cache::NWayLRU< T, U, Hash, Eq >::GetOr	(	const T &	key,
		const U &	default_value )

Returns cached value by key if present; otherwise returns default_value.

Parameters

key	Key to look up.
default_value	Value to return when key is not found.

Returns: Cached value if present, otherwise default_value.

Definition at line 191 of file nway_lru_cache.hpp.

◆ GetSize()

template<typename T, typename U, typename Hash, typename Eq>

size_t cache::NWayLRU< T, U, Hash, Eq >::GetSize ( ) const

Returns the total number of elements in the cache across all ways.

Returns: Total number of elements.

Definition at line 216 of file nway_lru_cache.hpp.

◆ Invalidate()

template<typename T, typename U, typename Hash, typename Eq>

void cache::NWayLRU< T, U, Hash, Eq >::Invalidate ( )

Removes all entries from the cache.

Definition at line 198 of file nway_lru_cache.hpp.

◆ InvalidateByKey()

template<typename T, typename U, typename Hash, typename Eq>

void cache::NWayLRU< T, U, Hash, Eq >::InvalidateByKey ( const T & key )

Removes the entry for the given key if present.

Parameters

key	Key whose entry is to be removed.

Definition at line 181 of file nway_lru_cache.hpp.

◆ Put()

template<typename T, typename U, typename Hash, typename Eq>

void cache::NWayLRU< T, U, Hash, Eq >::Put	(	const T &	key,
		U	value )

Stores value by key.

Parameters

key	Key to store the value under.
value	Value to store.

Definition at line 154 of file nway_lru_cache.hpp.

◆ Read()

template<typename T, typename U, typename Hash, typename Equal>

void cache::NWayLRU< T, U, Hash, Equal >::Read ( dump::Reader & reader )

Deserializes the cache contents from the dump reader.

Parameters

reader Source dump::Reader.

Note: Clears existing entries before loading.

Definition at line 262 of file nway_lru_cache.hpp.

◆ SetDumper()

template<typename T, typename U, typename Hash, typename Equal>

void cache::NWayLRU< T, U, Hash, Equal >::SetDumper ( std::shared_ptr< dump::Dumper > dumper )

Sets the dumper; it will be notified of any cache updates.

Parameters

dumper Instance of dump::Dumper, or nullptr to clear.

Note: This method is not thread-safe.

Definition at line 284 of file nway_lru_cache.hpp.

◆ UpdateWaySize()

template<typename T, typename U, typename Hash, typename Eq>

void cache::NWayLRU< T, U, Hash, Eq >::UpdateWaySize ( size_t way_size )

Updates maximum elements per way.

Parameters

way_size New maximum elements per way; see NWayLRU constructor for the semantics.

Definition at line 226 of file nway_lru_cache.hpp.

◆ VisitAll()

template<typename T, typename U, typename Hash, typename Eq>

template<typename Function>

void cache::NWayLRU< T, U, Hash, Eq >::VisitAll ( Function func ) const

Iterates over all items, invoking func for each (key, value).

Parameters

func	Callable to invoke for each item (e.g. void(const T&, const U&)).

Note: May be slow for big caches.

Definition at line 208 of file nway_lru_cache.hpp.

◆ Write()

template<typename T, typename U, typename Hash, typename Equal>

void cache::NWayLRU< T, U, Hash, Equal >::Write ( dump::Writer & writer ) const

Serializes the cache contents to the dump writer.

Parameters

writer Target dump::Writer.

Definition at line 246 of file nway_lru_cache.hpp.

The documentation for this class was generated from the following file:

userver/cache/nway_lru_cache.hpp

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ NWayLRU()

Member Function Documentation

◆ Get() [1/2]

◆ Get() [2/2]

◆ GetOr()

◆ GetSize()

◆ Invalidate()

◆ InvalidateByKey()

◆ Put()

◆ Read()

◆ SetDumper()

◆ UpdateWaySize()

◆ VisitAll()

◆ Write()