userver: userver/cache/cache_update_trait.hpp Source File
Loading...
Searching...
No Matches
cache_update_trait.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/cache/cache_update_trait.hpp
4/// @brief @copybrief cache::CacheUpdateTrait
5
6#include <memory>
7#include <string>
8
9#include <userver/cache/cache_statistics.hpp>
10#include <userver/cache/update_type.hpp>
11#include <userver/components/component_fwd.hpp>
12#include <userver/dump/fwd.hpp>
13#include <userver/engine/task/task_processor_fwd.hpp>
14#include <userver/rcu/fwd.hpp>
15#include <userver/utils/flags.hpp>
16
17USERVER_NAMESPACE_BEGIN
18
19namespace cache {
20
21struct CacheDependencies;
22struct Config;
23
24/// @ingroup userver_base_classes
25///
26/// @brief Base class for periodically updated caches.
27///
28/// @note Don't use directly, inherit from components::CachingComponentBase
29/// instead
31 public:
32 CacheUpdateTrait(CacheUpdateTrait&&) = delete;
33 CacheUpdateTrait& operator=(CacheUpdateTrait&&) = delete;
34
35 /// @brief Non-blocking forced cache update of specified type
36 /// @see PeriodicTask::ForceStepAsync for behavior details
37 void InvalidateAsync(UpdateType update_type);
38
39 /// @brief Forces a cache update of specified type
40 /// @throws If `Update` throws
41 void UpdateSyncDebug(UpdateType update_type);
42
43 /// @return name of the component
44 const std::string& Name() const;
45
46 protected:
47 /// @cond
48 // For internal use only
49 CacheUpdateTrait(const components::ComponentConfig& config,
50 const components::ComponentContext& context);
51
52 // For internal use only
53 explicit CacheUpdateTrait(CacheDependencies&& dependencies);
54
55 virtual ~CacheUpdateTrait();
56 /// @endcond
57
58 /// Update types configured for the cache
60
61 /// Periodic update flags
62 enum class Flag {
63 kNone = 0,
64 kNoFirstUpdate = 1 << 0, ///< Disable initial update on start
65 };
66
67 /// Starts periodic updates
68 void StartPeriodicUpdates(utils::Flags<Flag> flags = {});
69
70 /// @brief Stops periodic updates
71 /// @warning Should be called in destructor of derived class.
73
74 void AssertPeriodicUpdateStarted();
75
76 /// Called in `CachingComponentBase::Set` during update to indicate
77 /// that the cached data has been modified
79
80 /// @cond
81 // For internal use only
82 rcu::ReadablePtr<Config> GetConfig() const;
83
84 // Checks for the presence of the flag for pre-assign check.
85 // For internal use only.
86 bool HasPreAssignCheck() const;
87
88 // For internal use only.
89 void SetDataSizeStatistic(std::size_t size) noexcept;
90
91 // For internal use only
92 // TODO remove after TAXICOMMON-3959
93 engine::TaskProcessor& GetCacheTaskProcessor() const;
94 /// @endcond
95
96 /// @brief Should be overridden in a derived class to align the stored data
97 /// with some data source.
98 ///
99 /// `Update` implementation should do one of the following:
100 ///
101 /// A. If the update succeeded and has changes...
102 /// 1. call CachingComponentBase::Set to update the stored value and send a
103 /// notification to subscribers
104 /// 2. call UpdateStatisticsScope::Finish
105 /// 3. return normally (an exception is allowed in edge cases)
106 /// B. If the update succeeded and verified that there are no changes...
107 /// 1. DON'T call CachingComponentBase::Set
108 /// 2. call UpdateStatisticsScope::FinishNoChanges
109 /// 3. return normally (an exception is allowed in edge cases)
110 /// C. If the update failed...
111 /// 1. DON'T call CachingComponentBase::Set
112 /// 2. call UpdateStatisticsScope::FinishWithError, or...
113 /// 3. throw an exception, which will be logged nicely
114 ///
115 /// @param type type of the update
116 /// @param last_update time of the last update (value of `now` from previous
117 /// invocation of Update or default constructed value if this is the first
118 /// Update).
119 /// @param now current time point
120 ///
121 /// @throws std::exception on update failure
122 ///
123 /// @warning If `Update` returns without throwing an exception and without
124 /// calling one of the `Finish*` methods, the behavior is undefined.
125 ///
126 /// @see @ref scripts/docs/en/userver/caches.md
127 virtual void Update(UpdateType type,
128 const std::chrono::system_clock::time_point& last_update,
129 const std::chrono::system_clock::time_point& now,
130 UpdateStatisticsScope& stats_scope) = 0;
131
132 private:
133 virtual void Cleanup() = 0;
134
135 virtual void MarkAsExpired();
136
137 virtual void GetAndWrite(dump::Writer& writer) const;
138
139 virtual void ReadAndSet(dump::Reader& reader);
140
141 class Impl;
142 std::unique_ptr<Impl> impl_;
143};
144
145} // namespace cache
146
147USERVER_NAMESPACE_END