#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.

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

`first-update-mode` modes

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/http_caching.cpp.

Definition at line 125 of file caching_component_base.hpp.

Inheritance diagram for components::CachingComponentBase< T >:

Collaboration 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 ()

Public Member Functions inherited from components::LoggableComponentBase
	LoggableComponentBase (const ComponentConfig &, const ComponentContext &)

	LoggableComponentBase (LoggableComponentBase &&)=delete

	LoggableComponentBase (const LoggableComponentBase &)=delete

	~LoggableComponentBase () override=default

ComponentHealth	GetComponentHealth () const override

void	OnLoadingCancelled () override

void	OnAllComponentsLoaded () override

void	OnAllComponentsAreStopping () override

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

Static Public Member Functions inherited from components::LoggableComponentBase
static yaml_config::Schema	GetStaticConfigSchema ()

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

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.


virtual void	WriteContents (dump::Writer &writer, const T &contents) const

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

Protected Member Functions inherited from cache::CacheUpdateTrait
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	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.

	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 cache update of specified type.

const std::string &	Name () const

Additional Inherited Members
Protected Types inherited from cache::CacheUpdateTrait
enum class	Flag { kNone = 0 , kNoFirstUpdate = 1 << 0 }
	Periodic update flags. More...

Member Typedef Documentation

◆ DataType

template<typename T >

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

Definition at line 133 of file caching_component_base.hpp.

Constructor & Destructor Documentation

◆ CachingComponentBase()

template<typename T >

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

Definition at line 206 of file caching_component_base.hpp.

◆ ~CachingComponentBase()

template<typename T >

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

override

Definition at line 219 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 299 of file caching_component_base.hpp.

◆ Emplace()

template<typename T >

template<typename... Args>

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

protected

Definition at line 294 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.

Definition at line 228 of file caching_component_base.hpp.

◆ GetEventChannel()

template<typename T >

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

Definition at line 249 of file caching_component_base.hpp.

◆ GetStaticConfigSchema()

template<typename T >

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

static

Definition at line 369 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 254 of file caching_component_base.hpp.

◆ MayReturnNull()

template<typename T >

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

protectedvirtual

Whether Get() is expected to return nullptr. If MayReturnNull() returns false, Get() throws an exception instead of returning nullptr.

Definition at line 304 of file caching_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 374 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 337 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 259 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 288 of file caching_component_base.hpp.

◆ 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 238 of file caching_component_base.hpp.

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

Dynamic config

Static options:

Update types

Avoiding memory leaks

first-update-mode modes

testsuite-force-periodic-update

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Member Typedef Documentation

◆ DataType

Constructor & Destructor Documentation

◆ CachingComponentBase()

◆ ~CachingComponentBase()

Member Function Documentation

◆ Clear()

◆ Emplace()

◆ Get()

◆ GetEventChannel()

◆ GetStaticConfigSchema()

◆ GetUnsafe()

◆ MayReturnNull()

◆ PreAssignCheck()

◆ ReadContents()

◆ Set() [1/2]

◆ Set() [2/2]

◆ UpdateAndListen()

◆ WriteContents()

`first-update-mode` modes