Base class for caching components. More...

#include <userver/cache/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)

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

void	Clear ()

virtual bool	MayReturnNull () const


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

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 interval may be adjusted for requests dispersal	update_interval / 10
full-update-interval	interval between full updates	–
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).

<tt>first-update-mode</tt> 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 112 of file caching_component_base.hpp.

Member Typedef Documentation

◆ DataType

template<typename T >

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

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

◆ ~CachingComponentBase()

template<typename T >

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

override

Definition at line 197 of file caching_component_base.hpp.

Member Function Documentation

◆ Clear()

template<typename T >

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

protected

Definition at line 277 of file caching_component_base.hpp.

◆ Emplace()

template<typename T >

template<typename... Args>

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

protected

Definition at line 272 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 206 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 227 of file caching_component_base.hpp.

◆ GetStaticConfigSchema()

template<typename T >

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

static

Definition at line 341 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 232 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 282 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 309 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

Definition at line 237 of file caching_component_base.hpp.

◆ Set() [2/2]

template<typename T >

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

protected

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

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

userver/cache/caching_component_base.hpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Dynamic config

Static options:

Update types

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

testsuite-force-periodic-update

Member Typedef Documentation

◆ DataType

Constructor & Destructor Documentation

◆ CachingComponentBase()

◆ ~CachingComponentBase()

Member Function Documentation

◆ Clear()

◆ Emplace()

◆ Get()

◆ GetEventChannel()

◆ GetStaticConfigSchema()

◆ GetUnsafe()

◆ MayReturnNull()

◆ ReadContents()

◆ Set() [1/2]

◆ Set() [2/2]

◆ UpdateAndListen()

◆ WriteContents()