#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. 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 of components::CachingComponentBase :

Options inherited from components::ComponentBase :

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). Warning: use carefully. If the cache loses any data, it is lost until service restart (in the worst case). If possible, use full-and-incremental with rare full updates, and completely avoid only-incremental. Also you have to explicitly remove outdated items from the cache container, otherwise the cache might grow indefinitely and eventually will lead to OOM. If not sure, just use full-and-incremental.

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

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	OnAllComponentsLoaded () 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.

void	Attach (const std::shared_ptr< const T > &value_ptr)

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


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 144 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 225 of file caching_component_base.hpp.

◆ ~CachingComponentBase()

template<typename T >

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

override

Definition at line 240 of file caching_component_base.hpp.

Member Function Documentation

◆ Attach()

template<typename T >

void components::CachingComponentBase< T >::Attach ( const std::shared_ptr< const T > & value_ptr )

protected

Attach the value of cache. As a result the Get() member function starts returning the value passed into this function after the Update() finishes. Does not take over into sole ownership. Do not use unless absolutely necessary. The object must be strictly thread-safe.

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

Definition at line 288 of file caching_component_base.hpp.

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

◆ Emplace()

template<typename T >

template<typename... Args>

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

protected

Definition at line 301 of file caching_component_base.hpp.

◆ Get()

template<typename T >

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

finalvirtual

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

Implements cache::DataProvider< T >.

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

◆ GetStaticConfigSchema()

template<typename T >

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

static

Definition at line 380 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 273 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 311 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.

◆ OnAllComponentsLoaded()

void components::ComponentBase::OnAllComponentsLoaded ( )

inlineoverridevirtualinherited

Component may use this function to finalize registration of other components that depend on it (for example, handler components register in server component, and the latter uses OnAllComponentsLoaded() to start processing requests).

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

Reimplemented from components::RawComponentBase.

Reimplemented in urabbitmq::ConsumerComponentBase, components::Server, and server::handlers::Ping.

Definition at line 51 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 385 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 345 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 278 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 283 of file caching_component_base.hpp.

◆ 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 260 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 336 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 of components::CachingComponentBase :

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

◆ Attach()

◆ Clear()

◆ Emplace()

◆ Get()

◆ GetComponentHealth()

◆ GetEventChannel()

◆ GetStaticConfigSchema()

◆ GetUnsafe()

◆ InvalidateAsync()

◆ MayReturnNull()

◆ Name()

◆ OnAllComponentsAreStopping()

◆ OnAllComponentsLoaded()

◆ OnCacheModified()

◆ OnLoadingCancelled()

◆ PreAssignCheck()

◆ ReadContents()

◆ Set() [1/2]

◆ Set() [2/2]

◆ Update()

◆ UpdateAndListen()

◆ UpdateSyncDebug()

◆ WriteContents()