userver: components::CachingComponentBase< T > Class Template Reference
Loading...
Searching...
No Matches
components::CachingComponentBase< T > Class Template Referenceabstract

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

first-update-mode 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/http_caching.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
 Legacy alias, use ComponentBase instead.
 
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

Legacy alias, use 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::EmptyCacheErrorif 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.

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

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

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

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

C. If the update failed...

  1. DON'T call CachingComponentBase::Set
  2. call UpdateStatisticsScope::FinishWithError, or...
  3. throw an exception, which will be logged nicely (if there already is an exception, prefer rethrowing it instead of calling UpdateStatisticsScope::FinishWithError)
Parameters
typetype of the update
last_updatetime of the last update (value of now from previous invocation of Update or default constructed value if this is the first Update).
nowcurrent time point
Exceptions
std::exceptionon 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
IfUpdate 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: