userver: userver/dump/dumper.hpp Source File
Loading...
Searching...
No Matches
dumper.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/dump/dumper.hpp
4/// @brief @copybrief dump::Dumper
5
6#include <chrono>
7#include <memory>
8#include <optional>
9#include <string>
10
11#include <userver/components/component_fwd.hpp>
12#include <userver/dump/helpers.hpp>
13#include <userver/dump/operations.hpp>
14#include <userver/dynamic_config/fwd.hpp>
15#include <userver/engine/task/task_processor_fwd.hpp>
16#include <userver/utils/fast_pimpl.hpp>
17#include <userver/yaml_config/fwd.hpp>
18
19USERVER_NAMESPACE_BEGIN
20
21namespace utils::statistics {
22class Storage;
23} // namespace utils::statistics
24
25namespace testsuite {
26class DumpControl;
27} // namespace testsuite
28
29/// Dumping of cache-like components
30namespace dump {
31
32struct Config;
34extern const std::string_view kDump;
35
36/// A dynamically dispatched equivalent of `kDumpable` "concept". Unlike
37/// with ADL-found `Write`/`Read`, the methods are guaranteed not to be called
38/// in parallel.
40public:
41 virtual ~DumpableEntity();
42
43 virtual void GetAndWrite(dump::Writer& writer) const = 0;
44
45 virtual void ReadAndSet(dump::Reader& reader) = 0;
46};
47
48enum class UpdateType {
49 /// Some new data has appeared since the last update. `Dumper` will write it
50 /// on the next `WriteDumpAsync` call, or as specified by the config.
52
53 /// There is no new data, but we have verified that the old data is
54 /// up-to-date. `Dumper` will bump the dump modification time to `now`.
56};
57
58/// @brief Manages dumps of a cache-like component
59///
60/// The class is thread-safe.
61///
62/// Used in `components::CachingComponentBase`.
63///
64/// Automatically subscribes to:
65/// - dynamic config updates from `USERVER_DUMPS` under `dumper_name`
66/// - statistics under `cache.{dumper_name}.dump`
67///
68/// Dumps will be stored in `{dump-root}/{dumper_name}`, where `dump-root` is
69/// taken from `components::DumpConfigurator`.
70///
71/// Here, `dumper_name` is the name of the parent component.
72///
73/// ## Dumper Dynamic config
74/// * @ref USERVER_DUMPS
75///
76/// ## Static config of @ref dump::Dumper :
77/// @include{doc} scripts/docs/en/components_schema/core/src/dump/dumper.md
78///
79/// Options inherited from @ref components::ComponentBase :
80/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
81///
82/// ## Sample usage
83/// @snippet core/src/dump/dumper_test.cpp Sample Dumper usage
84///
85/// @see components::DumpConfigurator
86class Dumper final {
87public:
88 /// @brief The primary constructor for when `Dumper` is stored in a component
89 /// @note `dumpable` must outlive this `Dumper`
91 const components::ComponentConfig& config,
92 const components::ComponentContext& context,
93 DumpableEntity& dumpable
94 );
95
96 /// For internal use only
98 const Config& initial_config,
99 std::unique_ptr<OperationsFactory> rw_factory,
100 engine::TaskProcessor& fs_task_processor,
101 dynamic_config::Source config_source,
102 utils::statistics::Storage& statistics_storage,
103 testsuite::DumpControl& dump_control,
104 DumpableEntity& dumpable
105 );
106
107 Dumper(Dumper&&) = delete;
108 Dumper& operator=(Dumper&&) = delete;
109 ~Dumper();
110
111 const std::string& Name() const;
112
113 /// @brief Read data from a dump, if any
114 /// @note Catches and logs any exceptions related to read operation failure
115 /// @returns `update_time` of the loaded dump on success, `null` otherwise
116 std::optional<TimePoint> ReadDump();
117
118 /// @brief Forces the `Dumper` to write a dump synchronously
119 /// @throws std::exception if the `Dumper` failed to write a dump
121
122 /// @brief Forces the `Dumper` to read from a dump synchronously
123 /// @throws std::exception if the `Dumper` failed to read a dump
125
126 /// @brief Notifies the `Dumper` of an update in the `DumpableEntity`
127 ///
128 /// A dump will be written asynchronously as soon as:
129 ///
130 /// 1. data update has been reported via `OnUpdateCompleted` since the last
131 /// written dump,
132 /// 2. dumps are `enabled` in the dynamic config, and
133 /// 3. `min-interval` time has passed
134 ///
135 /// @note This overload is more performant. The time written on the dump will
136 /// be taken from the dump writing time.
138
139 /// @see void OnUpdateCompleted()
140 /// @param update_time The time at which the data has been guaranteed to be
141 /// up-to-date
142 /// @param update_type Whether the update modified the data or confirmed its
143 /// actuality, UpdateType::kModified by default
144 /// @note This overload locks mutexes and should not be used in tight loops.
145 /// On the other hand, it allows to exactly control the dump expiration.
146 void OnUpdateCompleted(TimePoint update_time, UpdateType update_type);
147
148 /// @brief Cancel and wait for the task running background writes. Also
149 /// disables operations via testsuite dump control.
150 ///
151 /// CancelWriteTaskAndWait is automatically called in the destructor. This
152 /// method must be called explicitly if the `DumpableEntity` may start its
153 /// destruction before the `Dumper` is destroyed.
154 ///
155 /// After calling this method, OnUpdateCompleted calls have no effect.
157
158 /// @brief Returns the static config schema for a
159 /// components::ComponentBase with an added `dump` sub-section.
161
162private:
163 Dumper(const Config& initial_config, const components::ComponentContext& context, DumpableEntity& dumpable);
164
165 class Impl;
166 utils::FastPimpl<Impl, 1120, 16> impl_;
167};
168
169} // namespace dump
170
171USERVER_NAMESPACE_END