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
65 /// @brief Disable initial update on start
66 /// @deprecated Use `first-update-fail-ok: true` instead
67 kNoFirstUpdate = 1 << 0,
68 };
69
70 /// Starts periodic updates
71 void StartPeriodicUpdates(utils::Flags<Flag> flags = {});
72
73 /// @brief Stops periodic updates
74 /// @warning Should be called in destructor of derived class.
76
77 void AssertPeriodicUpdateStarted();
78
79 void AssertPeriodicUpdateStopped();
80
81 /// Called in `CachingComponentBase::Set` during update to indicate
82 /// that the cached data has been modified
84
85 /// @cond
86 // For internal use only
87 rcu::ReadablePtr<Config> GetConfig() const;
88
89 // Checks for the presence of the flag for pre-assign check.
90 // For internal use only.
91 bool HasPreAssignCheck() const;
92
93 // Returns value of the flag safe-data-lifetime.
94 // For internal use only.
95 bool IsSafeDataLifetime() const;
96
97 // For internal use only.
98 void SetDataSizeStatistic(std::size_t size) noexcept;
99
100 // For internal use only
101 // TODO remove after TAXICOMMON-3959
102 engine::TaskProcessor& GetCacheTaskProcessor() const;
103 /// @endcond
104
105 /// @brief Should be overridden in a derived class to align the stored data
106 /// with some data source.
107 ///
108 /// `Update` implementation should do one of the following:
109 ///
110 /// A. If the update succeeded and has changes...
111 /// 1. call CachingComponentBase::Set to update the stored value and send a
112 /// notification to subscribers
113 /// 2. call UpdateStatisticsScope::Finish
114 /// 3. return normally (an exception is allowed in edge cases)
115 ///
116 /// B. If the update succeeded and verified that there are no changes...
117 /// 1. DON'T call CachingComponentBase::Set
118 /// 2. call UpdateStatisticsScope::FinishNoChanges
119 /// 3. return normally (an exception is allowed in edge cases)
120 ///
121 /// C. If the update failed...
122 /// 1. DON'T call CachingComponentBase::Set
123 /// 2. call UpdateStatisticsScope::FinishWithError, or...
124 /// 3. throw an exception, which will be logged nicely
125 /// (if there already is an exception, prefer rethrowing it instead
126 /// of calling UpdateStatisticsScope::FinishWithError)
127 ///
128 /// @param type type of the update
129 /// @param last_update time of the last update (value of `now` from previous
130 /// invocation of Update or default constructed value if this is the first
131 /// Update).
132 /// @param now current time point
133 ///
134 /// @throws std::exception on update failure
135 ///
136 /// @warning If `Update` returns without throwing an exception and without
137 /// calling one of the `Finish*` methods, the behavior is undefined.
138 ///
139 /// @see @ref scripts/docs/en/userver/caches.md
140 virtual void Update(UpdateType type,
141 const std::chrono::system_clock::time_point& last_update,
142 const std::chrono::system_clock::time_point& now,
143 UpdateStatisticsScope& stats_scope) = 0;
144
145 private:
146 virtual void Cleanup() = 0;
147
148 virtual void MarkAsExpired();
149
150 virtual void GetAndWrite(dump::Writer& writer) const;
151
152 virtual void ReadAndSet(dump::Reader& reader);
153
154 class Impl;
155 std::unique_ptr<Impl> impl_;
156};
157
158} // namespace cache
159
160USERVER_NAMESPACE_END