#include <userver/cache/cache_update_trait.hpp>

Detailed Description

Base class for periodically updated caches.

Note: Don't use directly, inherit from components::CachingComponentBase instead

Definition at line 30 of file cache_update_trait.hpp.

Inheritance diagram for cache::CacheUpdateTrait:

Public Member Functions
	CacheUpdateTrait (CacheUpdateTrait &&)=delete

CacheUpdateTrait &	operator= (CacheUpdateTrait &&)=delete

void	InvalidateAsync (UpdateType update_type)
	Non-blocking forced cache update of specified type.

void	UpdateSyncDebug (UpdateType update_type)
	Forces a synchronous cache update of specified type.

const std::string &	Name () const noexcept

Protected Types
enum class	Flag { kNone = 0 , kNoFirstUpdate = 1 << 0 }
	Periodic update flags. More...

Protected Member Functions
AllowedUpdateTypes	GetAllowedUpdateTypes () const
	Update types configured for the cache.

void	OnCacheModified () noexcept

virtual void	Update (UpdateType type, const std::chrono::system_clock::time_point &last_update, const std::chrono::system_clock::time_point &now, UpdateStatisticsScope &stats_scope)=0
	Should be overridden in a derived class to align the stored data with some data source.

virtual utils::Flags< Flag >	GetStartFlags () const
	Returns flags for cache start.

void	EarlyStartPeriodicUpdates (utils::Flags< Flag > flags)
	Call this to start periodic updates just now, not after the constructor.

Member Enumeration Documentation

◆ Flag

enum class cache::CacheUpdateTrait::Flag

strongprotected

Periodic update flags.

Enumerator

kNoFirstUpdate

Disable initial update on start.

Deprecated: Use first-update-fail-ok: true instead

Definition at line 89 of file cache_update_trait.hpp.

Member Function Documentation

◆ InvalidateAsync()

void cache::CacheUpdateTrait::InvalidateAsync ( UpdateType update_type )

Non-blocking forced cache update of specified type.

See also: PeriodicTask::ForceStepAsync for behavior details

◆ Name()

const std::string & cache::CacheUpdateTrait::Name ( ) const

noexcept

Returns: name of the component

◆ OnCacheModified()

void cache::CacheUpdateTrait::OnCacheModified ( )

protectednoexcept

Called in CachingComponentBase::Set during update to indicate that the cached data has been modified

◆ Update()

virtual void cache::CacheUpdateTrait::Update	(	UpdateType	type,
		const std::chrono::system_clock::time_point &	last_update,
		const std::chrono::system_clock::time_point &	now,
		UpdateStatisticsScope &	stats_scope )

protectedpure virtual

Should be overridden in a derived class to align the stored data with some data source.

Update implementation should do one of the following:

A. If the update succeeded and has changes...

call CachingComponentBase::Set to update the stored value and send a notification to subscribers
call UpdateStatisticsScope::Finish
return normally (an exception is allowed in edge cases)

B. If the update succeeded and verified that there are no changes...

DON'T call CachingComponentBase::Set
call UpdateStatisticsScope::FinishNoChanges
return normally (an exception is allowed in edge cases)

C. If the update failed...

DON'T call CachingComponentBase::Set
call UpdateStatisticsScope::FinishWithError, or...
throw an exception, which will be logged nicely (if there already is an exception, prefer rethrowing it instead of calling UpdateStatisticsScope::FinishWithError)

Parameters

type	type of the update
last_update	time of the last update (value of `now` from previous invocation of Update or default constructed value if this is the first Update).
now	current time point
stats_scope	the scope that expects one of `Finish`, `FinishNoChanges`, `FinishWithError` or an exception.

Exceptions

std::exception on update failure

Warning: If Update returns without throwing an exception and without calling one of the Finish* methods, the behavior is undefined.

See also: Basics of Caches

◆ UpdateSyncDebug()

void cache::CacheUpdateTrait::UpdateSyncDebug ( UpdateType update_type )

Forces a synchronous cache update of specified type.

Warning: This method is intended for tests and debugging only. In production code use InvalidateAsync instead. The reasons are:

InvalidateAsync shifts the time of the next update as if a periodic update has just happened. UpdateSyncDebug does not do that: it locks the mutex and performs an additional update on the side, which puts extra load on the CPU and on the data source.
The cache we subscribe to sends events as part of its own update. If the callback does something lengthy, e.g. updating another cache, this affects the cache we subscribe to: it may disrupt its updates and cause a traffic jam in the whole chain of caches. InvalidateAsync is not subject to this. On top of that, UpdateSyncDebug will block the cache we subscribe to for the time we wait for the previous update of the dependent cache to finish (if one was in progress).
InvalidateAsync robustly handles situations with repeated update requests, see the docs of PeriodicTask::ForceStepAsync, on top of which it is implemented. UpdateSyncDebug tries to lock the mutex over and over and performs as many updates as were requested, even if they were requested many times in a row.
If UpdateSyncDebug is called before the periodic updates of the current cache have started (they start after the constructor of the derived cache finishes), the behavior is undefined, because the state of the periodic updates is not set up yet, while an update was already requested. InvalidateAsync handles this case: in that situation nothing happens.

See also: InvalidateAsync