userver: userver/testsuite/cache_control.hpp Source File
Loading...
Searching...
No Matches
cache_control.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/testsuite/cache_control.hpp
4/// @brief @copybrief testsuite::CacheControl
5
6#include <functional>
7#include <memory>
8#include <string>
9#include <type_traits>
10#include <unordered_set>
11
12#include <userver/cache/update_type.hpp>
13#include <userver/components/component_fwd.hpp>
14#include <userver/utils/assert.hpp>
15
16USERVER_NAMESPACE_BEGIN
17
18namespace cache {
20struct Config;
21} // namespace cache
22
23namespace components::impl {
24class ComponentBase;
25} // namespace components::impl
26
27namespace testsuite {
28
29namespace impl {
30enum class PeriodicUpdatesMode { kDefault, kEnabled, kDisabled };
31} // namespace impl
32
33class CacheResetRegistration;
34
35/// @brief Testsuite interface for caches and cache-like components.
36///
37/// If a component stores transient state that may be carried between tests,
38/// or stores caches that may become stale, then it should register its resetter
39/// here. Example:
40///
41/// @snippet testsuite/cache_control_test.cpp sample
42///
43/// Testsuite will then call this hook in the beginning of each test.
44/// You can also reset a specific cache in testsuite explicitly as follows:
45///
46/// @code
47/// service_client.invalidate_caches(names=['your-cache-name'])
48/// @endcode
49///
50/// CacheControl is normally acquired through testsuite::FindCacheControl.
51///
52/// All methods are coro-safe.
53class CacheControl final {
54 public:
55 /// @brief Register a cache reset function. The returned handle must be kept
56 /// alive to keep supporting cache resetting.
57 ///
58 /// @warning The function should be called in the component's constructor
59 /// *after* all FindComponent calls. This ensures that reset will first be
60 /// called for dependencies, then for dependent components.
61 template <typename Component>
62 CacheResetRegistration RegisterCache(Component* self, std::string_view name,
63 void (Component::*reset_method)());
64
65 /// @brief Reset all the registered caches.
66 ///
67 /// @a update_type is used by caches derived from
68 /// @a component::CachingComponentBase.
70 cache::UpdateType update_type,
71 const std::unordered_set<std::string>& force_incremental_names);
72
73 /// @brief Reset caches with the specified @a names.
74 ///
75 /// @a update_type is used by caches derived from
76 /// @a component::CachingComponentBase.
78 cache::UpdateType update_type,
79 std::unordered_set<std::string> reset_only_names,
80 const std::unordered_set<std::string>& force_incremental_names);
81
82 /// @cond
83 // For internal use only.
84 explicit CacheControl(impl::PeriodicUpdatesMode);
85 ~CacheControl();
86
87 CacheControl(CacheControl&&) = delete;
88 CacheControl& operator=(CacheControl&&) = delete;
89
90 // For internal use only.
91 bool IsPeriodicUpdateEnabled(const cache::Config& cache_config,
92 const std::string& cache_name) const;
93
94 // For internal use only.
95 CacheResetRegistration RegisterPeriodicCache(cache::CacheUpdateTrait& cache);
96
97 private:
98 friend class CacheResetRegistration;
99
100 struct CacheInfo final {
101 std::string name;
102 std::function<void(cache::UpdateType)> reset;
103 bool needs_span{true};
104 components::impl::ComponentBase* component = nullptr;
105 };
106
107 struct CacheInfoNode;
108 using CacheInfoIterator = CacheInfoNode*;
109
110 CacheInfoIterator DoRegisterCache(CacheInfo&& info);
111
112 void UnregisterCache(CacheInfoIterator) noexcept;
113
114 static void DoResetCache(const CacheInfo& info,
115 cache::UpdateType update_type);
116
117 struct Impl;
118 std::unique_ptr<Impl> impl_;
119};
120
121/// @brief RAII helper for testsuite registration. Must be kept alive to keep
122/// supporting cache resetting.
123/// @warning Make sure to always place CacheResetRegistration after the rest of
124/// the component's fields.
125/// @see testsuite::CacheControl
126class [[nodiscard]] CacheResetRegistration final {
127 public:
128 CacheResetRegistration() noexcept;
129
130 CacheResetRegistration(CacheResetRegistration&&) noexcept;
131 CacheResetRegistration& operator=(CacheResetRegistration&&) noexcept;
132 ~CacheResetRegistration();
133
134 /// Unregister the cache component explicitly.
135 /// `Unregister` is called in the destructor automatically.
136 void Unregister() noexcept;
137
138 /// @cond
139 // For internal use only.
140 CacheResetRegistration(CacheControl&, CacheControl::CacheInfoIterator);
141 /// @endcond
142
143 private:
144 CacheControl* cache_control_{nullptr};
145 CacheControl::CacheInfoIterator cache_info_iterator_{};
146};
147
148/// The method for acquiring testsuite::CacheControl in the component system.
149///
150/// @see testsuite::RegisterCache
151CacheControl& FindCacheControl(const components::ComponentContext& context);
152
153/// The method for registering a cache from component constructor.
154template <typename Component>
155CacheResetRegistration RegisterCache(
156 const components::ComponentConfig& config,
157 const components::ComponentContext& context, Component* self,
158 void (Component::*reset_method)()) {
159 auto& cc = testsuite::FindCacheControl(context);
160 return cc.RegisterCache(self, components::GetCurrentComponentName(config),
161 reset_method);
162}
163
164template <typename Component>
165CacheResetRegistration CacheControl::RegisterCache(
166 Component* self, std::string_view name, void (Component::*reset_method)()) {
167 static_assert(std::is_base_of_v<components::impl::ComponentBase, Component>,
168 "CacheControl can only be used with components");
169 UASSERT(self);
170 UASSERT(reset_method);
171
172 CacheInfo info;
173 info.component = self;
174 info.name = std::string{name};
175 info.reset = [self, reset_method]([[maybe_unused]] cache::UpdateType) {
176 (self->*reset_method)();
177 };
178 info.needs_span = true;
179
180 auto iter = DoRegisterCache(std::move(info));
181 return CacheResetRegistration(*this, std::move(iter));
182}
183
184} // namespace testsuite
185
186USERVER_NAMESPACE_END