#include <userver/cache/caching_component_base.hpp>

Detailed Description

template<typename T>
class components::CachingComponentBase< T >

Base class for caching components.

Provides facilities for creating periodically updated caches. You need to override cache::CacheUpdateTrait::Update then call cache::CacheUpdateTrait::StartPeriodicUpdates after setup and cache::CacheUpdateTrait::StopPeriodicUpdates before teardown. You can also override cache::CachingComponentBase::PreAssignCheck and set has-pre-assign-check: true in the static config to enable check.

Caching components must be configured in service config (see options below) and may be reconfigured dynamically via components::DynamicConfig.

Basics of Caches provide a more detailed introduction.

CachingComponentBase Dynamic config

Static options:

Name	Description	Default value
update-types	specifies whether incremental and/or full updates will be used	see below
update-interval	(required) interval between Update invocations	–
update-jitter	max. amount of time by which update-interval may be adjusted for requests dispersal	update_interval / 10
full-update-interval	interval between full updates	–
full-update-jitter	max. amount of time by which full-update-interval may be adjusted for requests dispersal	full-update-interval / 10
updates-enabled	if false, cache updates are disabled (except for the first one if !first-update-fail-ok)	true
first-update-fail-ok	whether first update failure is non-fatal; see also MayReturnNull	false
task-processor	the name of the TaskProcessor for running DoWork	main-task-processor
config-settings	enables dynamic reconfiguration with CacheConfigSet	true
exception-interval	Used instead of `update-interval` in case of exception	update_interval
additional-cleanup-interval	how often to run background RCU garbage collector	10 seconds
is-strong-period	whether to include Update execution time in update-interval	false
testsuite-force-periodic-update	override testsuite-periodic-update-enabled in TestsuiteSupport component config	–
failed-updates-before-expiration	the number of consecutive failed updates for data expiration	–
has-pre-assign-check	enables the check before changing the value in the cache, by default it is the check that the new value is not empty	false
alert-on-failing-to-update-times	fire an alert if the cache update failed specified amount of times in a row. If zero - alerts are disabled. Value from dynamic config takes priority over static	0
safe-data-lifetime	enables awaiting data destructors in the component's destructor. Can be set to `false` if the stored data does not refer to the component and its dependencies.	true
dump.*	Manages cache behavior after dump load	-
dump.first-update-mode	Behavior of update after successful load from dump. See info on modes below	skip
dump.first-update-type	Update type after successful load from dump (`full`, `incremental` or `incremental-then-async-full`)	full

Update types

full-and-incremental: both update-interval and full-update-interval must be specified. Updates with UpdateType::kIncremental will be triggered each update-interval (adjusted by jitter) unless full-update-interval has passed and UpdateType::kFull is triggered.
only-full: only update-interval must be specified. UpdateType::kFull will be triggered each update-interval (adjusted by jitter).
only-incremental: only update-interval must be specified. UpdateType::kFull is triggered on the first update, afterwards UpdateType::kIncremental will be triggered each update-interval (adjusted by jitter).

Avoiding memory leaks

If you don't implement the deletion of objects that are deleted from the data source and don't use full updates, you may get an effective memory leak, because garbage objects will pile up in the cached data.

Calculation example:

size of database: 1000 objects
removal rate: 30 objects per minute (0.5 objects per second)

Let's say we allow 20% extra garbage objects in cache in addition to the actual objects from the database. In this case we need:

full-update-interval = (size-of-database * 20% / removal-rate) = 400s

Dealing with nullptr data in CachingComponentBase

The cache can become nullptr through multiple ways:

If the first cache update fails, and first-update-fail-ok config option is set to true (otherwise the service shutdown at start)
Through manually calling Set with nullptr in Update
If failed-updates-before-expiration is set, and that many periodic updates fail in a row

By default, the cache's user can expect that the pointer returned from Get will never be nullptr. If the cache for some reason is in nullptr state, then Get will throw. This is the safe default behavior for most cases.

If all systems of a service are expected to work with a cache in nullptr state, then such a cache should override MayReturnNull to return true. It will also serve self-documentation purposes: if a cache defines MayReturnNull, then pointers returned from Get should be checked for nullptr before usage.

<tt>first-update-mode</tt> modes

Further customizes the behavior of cache dumps.

Mode	Description
`skip`	after successful load from dump, do nothing
`required`	make a synchronous update of type `first-update-type`, stop the service on failure
`best-effort`	make a synchronous update of type `first-update-type`, keep working and use data from dump on failure

testsuite-force-periodic-update

use it to enable periodic cache update for a component in testsuite environment where testsuite-periodic-update-enabled from TestsuiteSupport config is false

By default, update types are guessed based on update intervals presence. If both update-interval and full-update-interval are present, full-and-incremental types is assumed. Otherwise only-full is used.

See also: dump::Dumper for more info on persistent cache dumps and corresponding config options.; Basics of Caches. pytest_userver.client.Client.invalidate_caches() for a function to force cache update from testsuite.

Examples: samples/http_caching/main.cpp.

Definition at line 153 of file caching_component_base.hpp.

Inheritance diagram for components::CachingComponentBase< T >:

Public Types
using	DataType = T

Public Member Functions
	CachingComponentBase (const ComponentConfig &config, const ComponentContext &)

utils::SharedReadablePtr< T >	Get () const

utils::SharedReadablePtr< T >	GetUnsafe () const

template<class Class >
concurrent::AsyncEventSubscriberScope	UpdateAndListen (Class obj, std::string name, void(Class::func)(const std::shared_ptr< const T > &))

concurrent::AsyncEventChannel< const std::shared_ptr< const T > & > &	GetEventChannel ()

ComponentHealth	GetComponentHealth () const override

void	OnLoadingCancelled () override

void	OnAllComponentsAreStopping () override

Static Public Member Functions
static yaml_config::Schema	GetStaticConfigSchema ()

Protected Types
using	LoggableComponentBase = ComponentBase

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

Protected Member Functions
void	Set (std::unique_ptr< const T > value_ptr)

void	Set (T &&value)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename... Args>
void	Emplace (Args &&... args)

void	Clear ()
	Clears the content of the cache by string a default constructed T.

virtual bool	MayReturnNull () const
	Whether Get is expected to return `nullptr`.

virtual void	PreAssignCheck (const T old_value_ptr, const T new_value_ptr) const
	If the option has-pre-assign-check is set true in static config, this function is called before assigning the new value to the cache.

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

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

const std::string &	Name () const

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

void	StartPeriodicUpdates (utils::Flags< Flag > flags={})
	Starts periodic updates.

void	StopPeriodicUpdates ()
	Stops periodic updates.

void	AssertPeriodicUpdateStarted ()

void	AssertPeriodicUpdateStopped ()

void	OnCacheModified ()

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 void	WriteContents (dump::Writer &writer, const T &contents) const

virtual std::unique_ptr< const T >	ReadContents (dump::Reader &reader) const

Member Typedef Documentation

◆ DataType

template<typename T >

using components::CachingComponentBase< T >::DataType = T

Definition at line 162 of file caching_component_base.hpp.

◆ LoggableComponentBase

using components::ComponentBase::LoggableComponentBase = ComponentBase

protectedinherited

Deprecated:: use components::ComponentBase instead.

Definition at line 67 of file component_base.hpp.

Member Enumeration Documentation

◆ Flag

enum class cache::CacheUpdateTrait::Flag

strongprotectedinherited

Periodic update flags.

Enumerator

kNoFirstUpdate

Disable initial update on start.

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

Definition at line 61 of file cache_update_trait.hpp.

Constructor & Destructor Documentation

◆ CachingComponentBase()

template<typename T >

components::CachingComponentBase< T >::CachingComponentBase	(	const ComponentConfig &	config,
		const ComponentContext &	context
	)

Definition at line 234 of file caching_component_base.hpp.

◆ ~CachingComponentBase()

template<typename T >

components::CachingComponentBase< T >::~CachingComponentBase ( )

override

Definition at line 245 of file caching_component_base.hpp.

Member Function Documentation

◆ Clear()

template<typename T >

void components::CachingComponentBase< T >::Clear ( )

protected

Clears the content of the cache by string a default constructed T.

Definition at line 311 of file caching_component_base.hpp.

◆ Emplace()

template<typename T >

template<typename... Args>

void components::CachingComponentBase< T >::Emplace ( Args &&... args )

protected

Definition at line 306 of file caching_component_base.hpp.

◆ Get()

template<typename T >

utils::SharedReadablePtr< T > components::CachingComponentBase< T >::Get ( ) const

Returns: cache contents. May be nullptr if and only if MayReturnNull returns true.

Exceptions

cache::EmptyCacheError if the contents are nullptr, and MayReturnNull returns false (which is the default behavior).

Definition at line 254 of file caching_component_base.hpp.

◆ GetComponentHealth()

ComponentHealth components::ComponentBase::GetComponentHealth ( ) const

inlineoverridevirtualinherited

Override this function to inform the world of the state of your component.

Warning: The function is called concurrently from multiple threads.

Reimplemented from components::RawComponentBase.

Reimplemented in server::handlers::Restart.

Definition at line 35 of file component_base.hpp.

◆ GetEventChannel()

template<typename T >

concurrent::AsyncEventChannel< const std::shared_ptr< const T > & > & components::CachingComponentBase< T >::GetEventChannel ( )

Definition at line 276 of file caching_component_base.hpp.

◆ GetStaticConfigSchema()

template<typename T >

yaml_config::Schema components::CachingComponentBase< T >::GetStaticConfigSchema ( )

static

Definition at line 388 of file caching_component_base.hpp.

◆ GetUnsafe()

template<typename T >

utils::SharedReadablePtr< T > components::CachingComponentBase< T >::GetUnsafe ( ) const

Returns: cache contents. May be nullptr regardless of MayReturnNull.

Definition at line 281 of file caching_component_base.hpp.

◆ InvalidateAsync()

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

inherited

Non-blocking forced cache update of specified type.

See also: PeriodicTask::ForceStepAsync for behavior details

◆ MayReturnNull()

template<typename T >

bool components::CachingComponentBase< T >::MayReturnNull ( ) const

protectedvirtual

Whether Get is expected to return nullptr.

Definition at line 316 of file caching_component_base.hpp.

◆ Name()

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

inherited

Returns: name of the component

◆ OnAllComponentsAreStopping()

void components::ComponentBase::OnAllComponentsAreStopping ( )

inlineoverridevirtualinherited

Component may use this function to stop doing work before the stop of the components that depend on it.

Base components may override it and make final to do some work before the derived object constructor is called. Don't use it otherwise.

Reimplemented from components::RawComponentBase.

Reimplemented in urabbitmq::ConsumerComponentBase, and components::Server.

Definition at line 58 of file component_base.hpp.

◆ OnCacheModified()

void cache::CacheUpdateTrait::OnCacheModified ( )

protectedinherited

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

◆ OnLoadingCancelled()

void components::ComponentBase::OnLoadingCancelled ( )

inlineoverridevirtualinherited

Called once if the creation of any other component failed. If the current component expects some other component to take any action with the current component, this call is a signal that such action may never happen due to components loading was cancelled. Application components might not want to override it.

Reimplemented from components::RawComponentBase.

Definition at line 42 of file component_base.hpp.

◆ PreAssignCheck()

template<typename T >

void components::CachingComponentBase< T >::PreAssignCheck	(	const T *	old_value_ptr,
		const T *	new_value_ptr
	)		const

protectedvirtual

If the option has-pre-assign-check is set true in static config, this function is called before assigning the new value to the cache.

Note: old_value_ptr and new_value_ptr can be nullptr.

Definition at line 393 of file caching_component_base.hpp.

◆ ReadContents()

template<typename T >

std::unique_ptr< const T > components::CachingComponentBase< T >::ReadContents ( dump::Reader & reader ) const

protectedvirtual

Definition at line 348 of file caching_component_base.hpp.

◆ Set() [1/2]

template<typename T >

void components::CachingComponentBase< T >::Set ( std::unique_ptr< const T > value_ptr )

protected

Sets the new value of cache. As a result the Get() member function starts returning the value passed into this function after the Update() finishes.

Warning: Do not forget to update cache::UpdateStatisticsScope, otherwise the behavior is undefined.

Definition at line 286 of file caching_component_base.hpp.

◆ Set() [2/2]

template<typename T >

void components::CachingComponentBase< T >::Set ( T && value )

protected

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 300 of file caching_component_base.hpp.

◆ StopPeriodicUpdates()

void cache::CacheUpdateTrait::StopPeriodicUpdates ( )

protectedinherited

Stops periodic updates.

Warning: Should be called in destructor of derived class.

◆ 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 virtualinherited

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

◆ UpdateAndListen()

template<typename T >

template<typename Class >

concurrent::AsyncEventSubscriberScope components::CachingComponentBase< T >::UpdateAndListen	(	Class *	obj,
		std::string	name,
		void(Class::*)(const std::shared_ptr< const T > &)	func
	)

Subscribes to cache updates using a member function. Also immediately invokes the function with the current cache contents.

Definition at line 264 of file caching_component_base.hpp.

◆ UpdateSyncDebug()

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

inherited

Forces a cache update of specified type.

Exceptions

If	`Update` throws

◆ WriteContents()

template<typename T >

void components::CachingComponentBase< T >::WriteContents	(	dump::Writer &	writer,
		const T &	contents
	)		const

protectedvirtual

Override to use custom serialization for cache dumps

Definition at line 339 of file caching_component_base.hpp.

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

userver/cache/caching_component_base.hpp

Detailed Description

CachingComponentBase Dynamic config

Static options:

Update types

Avoiding memory leaks

Dealing with nullptr data in CachingComponentBase

<tt>first-update-mode</tt> modes

testsuite-force-periodic-update

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Member Typedef Documentation

◆ DataType

◆ LoggableComponentBase

Member Enumeration Documentation

◆ Flag

Constructor & Destructor Documentation

◆ CachingComponentBase()

◆ ~CachingComponentBase()

Member Function Documentation

◆ Clear()

◆ Emplace()

◆ Get()

◆ GetComponentHealth()

◆ GetEventChannel()

◆ GetStaticConfigSchema()

◆ GetUnsafe()

◆ InvalidateAsync()

◆ MayReturnNull()

◆ Name()

◆ OnAllComponentsAreStopping()

◆ OnCacheModified()

◆ OnLoadingCancelled()

◆ PreAssignCheck()

◆ ReadContents()

◆ Set() [1/2]

◆ Set() [2/2]

◆ StopPeriodicUpdates()

◆ Update()

◆ UpdateAndListen()

◆ UpdateSyncDebug()

◆ WriteContents()