#include <userver/cache/expirable_lru_cache.hpp>

Detailed Description

template<typename Key, typename Value, typename Hash = std::hash<Key>, typename Equal = std::equal_to<Key>>
class cache::ExpirableLruCache< Key, Value, Hash, Equal >

Class for expirable LRU cache.

Use cache::LruMap for non-expirable LRU cache.

    using Key = std::string;
    using Value = int;
    using Cache = cache::ExpirableLruCache<Key, Value>;
 
    Cache cache(/*ways*/ 1, /*way_size*/ 1);
    cache.SetMaxLifetime(std::chrono::seconds(3));  // by default not bounded
 
    utils::datetime::MockNowSet(std::chrono::system_clock::now());
 
    const Key key1 = "first-key";
    const Key key2 = "second-key";
    cache.Put(key1, 41);
    EXPECT_EQ(41, cache.GetOptionalNoUpdate(key1));
    cache.Put(key2, 42);
    EXPECT_EQ(std::nullopt, cache.GetOptionalNoUpdate(key1));
    EXPECT_EQ(42, cache.GetOptionalNoUpdate(key2));
 
    utils::datetime::MockSleep(std::chrono::seconds(2));
    EXPECT_EQ(42, cache.GetOptionalNoUpdate(key2));
 
    utils::datetime::MockSleep(std::chrono::seconds(2));
    EXPECT_EQ(std::nullopt, cache.GetOptionalNoUpdate(key2));

Definition at line 58 of file expirable_lru_cache.hpp.

Public Types
enum class	ReadMode { kSkipCache , kUseCache }
	Cache read mode for Get. More...

using	UpdateValueFunc = std::function<Value(const Key&)>
	Type of function used to compute or refresh a value for a key.

Public Member Functions
	ExpirableLruCache (size_t ways, size_t way_size, const Hash &hash=Hash(), const Equal &equal=Equal())
	Constructs the cache.

	~ExpirableLruCache ()
	Destroys the cache and waits for all background update tasks to complete.

void	SetWaySize (size_t way_size)
	Sets maximum size per way.

std::chrono::milliseconds	GetMaxLifetime () const noexcept
	Returns the maximum lifetime of a cached value before it is considered expired.

void	SetMaxLifetime (std::chrono::milliseconds max_lifetime)
	Sets the maximum lifetime of a cached value before it is considered expired.

void	SetBackgroundUpdate (BackgroundUpdateMode background_update)
	Sets background update mode.

Value	Get (const Key &key, const UpdateValueFunc &update_func, ReadMode read_mode=ReadMode::kUseCache)
	Returns value by key, or computes and optionally caches it.

std::optional< Value >	GetOptional (const Key &key, const UpdateValueFunc &update_func)
	Returns value by key if present and not expired; may trigger background update.

std::optional< Value >	GetOptionalUnexpirable (const Key &key)
	GetOptional without expiry checks and without value updates.

std::optional< Value >	GetOptionalUnexpirableWithUpdate (const Key &key, const UpdateValueFunc &update_func)
	GetOptional without expiry check; may trigger background update.

std::optional< Value >	GetOptionalNoUpdate (const Key &key)
	GetOptional without triggering value updates (no background refresh).

std::optional< impl::ExpirableValue< Value > >	GetOptionalNoUpdateWithLastUpdateTime (const Key &key)
	GetOptionalNoUpdate, but returns the value together with its last update time.

void	Put (const Key &key, const Value &value)
	Inserts or updates the value for the given key with current timestamp.

void	Put (const Key &key, Value &&value)
	Inserts or updates the value for the given key with current timestamp (`value` is moved).

const impl::ExpirableLruCacheStatistics &	GetStatistics () const
	Returns cache statistics (hits, misses, background updates, etc.).

size_t	GetSizeApproximate () const
	Returns approximate number of entries in the cache.

void	Invalidate ()
	Clears the cache (removes all entries).

void	InvalidateByKey (const Key &key)
	Erases the entry for the given key.

template<typename Predicate>
void	InvalidateByKeyIf (const Key &key, Predicate pred)
	Erases the key from cache if `pred` returns true for the current value.

void	UpdateInBackground (const Key &key, UpdateValueFunc update_func)
	Schedules an async task to update the value by update_func(`key`).

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

void	Read (dump::Reader &reader)
	Restores cache state from the dump reader.

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

Member Typedef Documentation

◆ UpdateValueFunc

template<typename Key, typename Value, typename Hash = std::hash<Key>, typename Equal = std::equal_to<Key>>

using cache::ExpirableLruCache< Key, Value, Hash, Equal >::UpdateValueFunc = std::function<Value(const Key&)>

Type of function used to compute or refresh a value for a key.

Definition at line 61 of file expirable_lru_cache.hpp.

Member Enumeration Documentation

◆ ReadMode

template<typename Key, typename Value, typename Hash = std::hash<Key>, typename Equal = std::equal_to<Key>>

enum class cache::ExpirableLruCache::ReadMode

strong

Cache read mode for Get.

Enumerator
kSkipCache	Do not cache value got from update function.
kUseCache	Cache value got from update function.

Definition at line 64 of file expirable_lru_cache.hpp.

Constructor & Destructor Documentation

◆ ExpirableLruCache()

template<typename Key, typename Value, typename Hash, typename Equal>

cache::ExpirableLruCache< Key, Value, Hash, Equal >::ExpirableLruCache	(	size_t	ways,
		size_t	way_size,
		const Hash &	hash = Hash(),
		const Equal &	equal = Equal() )

Constructs the cache.

Parameters

ways	Number of ways (shards). See cache::NWayLRU.
way_size	Maximum size per way. See cache::NWayLRU.
hash	Hash functor for keys.
equal	Equality functor for keys.

Definition at line 249 of file expirable_lru_cache.hpp.

◆ ~ExpirableLruCache()

template<typename Key, typename Value, typename Hash, typename Equal>

cache::ExpirableLruCache< Key, Value, Hash, Equal >::~ExpirableLruCache ( )

Destroys the cache and waits for all background update tasks to complete.

Definition at line 255 of file expirable_lru_cache.hpp.

Member Function Documentation

◆ Get()

template<typename Key, typename Value, typename Hash, typename Equal>

Value cache::ExpirableLruCache< Key, Value, Hash, Equal >::Get	(	const Key &	key,
		const UpdateValueFunc &	update_func,
		ReadMode	read_mode = ReadMode::kUseCache )

Returns value by key, or computes and optionally caches it.

Equivalent to GetOptional(key, update_func); if that is std::nullopt, returns update_func(key) and stores it in cache when read_mode is ReadMode::kUseCache.

Parameters

key	Cache key.
update_func	Function to compute value when key is missing or expired.
read_mode	If kUseCache, caches the result of `update_func`.

Returns: Cached or freshly computed value.

Definition at line 284 of file expirable_lru_cache.hpp.

◆ GetMaxLifetime()

template<typename Key, typename Value, typename Hash, typename Equal>

std::chrono::milliseconds cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetMaxLifetime ( ) const

noexcept

Returns the maximum lifetime of a cached value before it is considered expired.

Returns: Current max lifetime, or zero if expiration is disabled.

Definition at line 265 of file expirable_lru_cache.hpp.

◆ GetOptional()

template<typename Key, typename Value, typename Hash, typename Equal>

std::optional< Value > cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetOptional	(	const Key &	key,
		const UpdateValueFunc &	update_func )

Returns value by key if present and not expired; may trigger background update.

If background update is kEnabled and the entry is near expiry, schedules an async update via update_func. Does not block on that update.

Parameters

key	Cache key.
update_func	Function used for background refresh when entry is near expiry.

Returns: Value if key is in cache and not expired, otherwise std::nullopt.

Definition at line 312 of file expirable_lru_cache.hpp.

◆ GetOptionalNoUpdate()

template<typename Key, typename Value, typename Hash, typename Equal>

std::optional< Value > cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetOptionalNoUpdate ( const Key & key )

GetOptional without triggering value updates (no background refresh).

Parameters

key	Cache key.

Returns: Value if key is in cache and not expired, otherwise std::nullopt.

Definition at line 391 of file expirable_lru_cache.hpp.

◆ GetOptionalNoUpdateWithLastUpdateTime()

template<typename Key, typename Value, typename Hash, typename Equal>

std::optional< impl::ExpirableValue< Value > > cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetOptionalNoUpdateWithLastUpdateTime ( const Key & key )

GetOptionalNoUpdate, but returns the value together with its last update time.

Parameters

key	Cache key.

Returns: Value and update time if key is in cache and not expired, otherwise std::nullopt.

Definition at line 375 of file expirable_lru_cache.hpp.

◆ GetOptionalUnexpirable()

template<typename Key, typename Value, typename Hash, typename Equal>

std::optional< Value > cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetOptionalUnexpirable ( const Key & key )

GetOptional without expiry checks and without value updates.

Parameters

key	Cache key.

Returns: Value if key is in cache, otherwise std::nullopt.

Note: Used during fallback in FallbackELruCache.

Definition at line 335 of file expirable_lru_cache.hpp.

◆ GetOptionalUnexpirableWithUpdate()

template<typename Key, typename Value, typename Hash, typename Equal>

std::optional< Value > cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetOptionalUnexpirableWithUpdate	(	const Key &	key,
		const UpdateValueFunc &	update_func )

GetOptional without expiry check; may trigger background update.

Parameters

key	Cache key.
update_func	Function used for background refresh when entry is near expiry.

Returns: Value if key is in cache, otherwise std::nullopt.

Note: Used during fallback in FallbackELruCache.

Definition at line 352 of file expirable_lru_cache.hpp.

◆ GetSizeApproximate()

template<typename Key, typename Value, typename Hash, typename Equal>

size_t cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetSizeApproximate ( ) const

Returns approximate number of entries in the cache.

Returns: Approximate size (sum of all ways).

Definition at line 415 of file expirable_lru_cache.hpp.

◆ GetStatistics()

template<typename Key, typename Value, typename Hash, typename Equal>

const impl::ExpirableLruCacheStatistics & cache::ExpirableLruCache< Key, Value, Hash, Equal >::GetStatistics ( ) const

Returns cache statistics (hits, misses, background updates, etc.).

Returns: Reference to impl::ExpirableLruCacheStatistics.

Definition at line 410 of file expirable_lru_cache.hpp.

◆ Invalidate()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::Invalidate ( )

Clears the cache (removes all entries).

Definition at line 420 of file expirable_lru_cache.hpp.

◆ InvalidateByKey()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::InvalidateByKey ( const Key & key )

Erases the entry for the given key.

Parameters

key	Cache key to erase.

Definition at line 425 of file expirable_lru_cache.hpp.

◆ InvalidateByKeyIf()

template<typename Key, typename Value, typename Hash, typename Equal>

template<typename Predicate>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::InvalidateByKeyIf	(	const Key &	key,
		Predicate	pred )

Erases the key from cache if pred returns true for the current value.

Parameters

key	Cache key.
pred	Predicate invoked with current value; entry is erased only if it returns true and value is not expired.

Definition at line 431 of file expirable_lru_cache.hpp.

◆ Put() [1/2]

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::Put	(	const Key &	key,
		const Value &	value )

Inserts or updates the value for the given key with current timestamp.

Parameters

key	Cache key.
value	Value to store.

Definition at line 400 of file expirable_lru_cache.hpp.

◆ Put() [2/2]

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::Put	(	const Key &	key,
		Value &&	value )

Inserts or updates the value for the given key with current timestamp (value is moved).

Parameters

key	Cache key.
value	Value to store (moved).

Definition at line 405 of file expirable_lru_cache.hpp.

◆ Read()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::Read ( dump::Reader & reader )

Restores cache state from the dump reader.

Used for dump::Dumper integration.

Parameters

reader Dump reader to read from.

Definition at line 565 of file expirable_lru_cache.hpp.

◆ SetBackgroundUpdate()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::SetBackgroundUpdate ( BackgroundUpdateMode background_update )

Sets background update mode.

If background_update is kDisabled, expiring values are not updated in background; if kEnabled, they are updated asynchronously when lifetime is near end.

Parameters

background_update Either kDisabled or kEnabled.

Definition at line 275 of file expirable_lru_cache.hpp.

◆ SetDumper()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::SetDumper ( std::shared_ptr< dump::Dumper > dumper )

Sets the dumper that will be notified of cache updates.

Parameters

dumper Shared pointer to dump::Dumper.

Note: This method is not thread-safe.

Definition at line 571 of file expirable_lru_cache.hpp.

◆ SetMaxLifetime()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::SetMaxLifetime ( std::chrono::milliseconds max_lifetime )

Sets the maximum lifetime of a cached value before it is considered expired.

Parameters

max_lifetime Max lifetime; zero disables expiration.

Definition at line 270 of file expirable_lru_cache.hpp.

◆ SetWaySize()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::SetWaySize ( size_t way_size )

Sets maximum size per way.

Parameters

way_size Maximum size per way. See cache::NWayLRU.

Definition at line 260 of file expirable_lru_cache.hpp.

◆ UpdateInBackground()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::UpdateInBackground	(	const Key &	key,
		UpdateValueFunc	update_func )

Schedules an async task to update the value by update_func(key).

Parameters

key	Cache key to update.
update_func	Function to compute the new value.

Definition at line 444 of file expirable_lru_cache.hpp.

◆ Write()

template<typename Key, typename Value, typename Hash, typename Equal>

void cache::ExpirableLruCache< Key, Value, Hash, Equal >::Write ( dump::Writer & writer ) const

Serializes cache state to the dump writer.

Used for dump::Dumper integration.

Parameters

writer Dump writer to write to.

Definition at line 559 of file expirable_lru_cache.hpp.

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

userver/cache/expirable_lru_cache.hpp

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

◆ UpdateValueFunc

Member Enumeration Documentation

◆ ReadMode

Constructor & Destructor Documentation

◆ ExpirableLruCache()

◆ ~ExpirableLruCache()

Member Function Documentation

◆ Get()

◆ GetMaxLifetime()

◆ GetOptional()

◆ GetOptionalNoUpdate()

◆ GetOptionalNoUpdateWithLastUpdateTime()

◆ GetOptionalUnexpirable()

◆ GetOptionalUnexpirableWithUpdate()

◆ GetSizeApproximate()

◆ GetStatistics()

◆ Invalidate()

◆ InvalidateByKey()

◆ InvalidateByKeyIf()

◆ Put() [1/2]

◆ Put() [2/2]

◆ Read()

◆ SetBackgroundUpdate()

◆ SetDumper()

◆ SetMaxLifetime()

◆ SetWaySize()

◆ UpdateInBackground()

◆ Write()