Github   Telegram
No Matches
Public Member Functions | Static Public Member Functions | List of all members
dump::Dumper Class Referencefinal

Manages dumps of a cache-like component. More...

#include <userver/dump/dumper.hpp>

Public Member Functions

 Dumper (const components::ComponentConfig &config, const components::ComponentContext &context, DumpableEntity &dumpable)
 The primary constructor for when Dumper is stored in a component. More...
 Dumper (const Config &initial_config, std::unique_ptr< OperationsFactory > rw_factory, engine::TaskProcessor &fs_task_processor, dynamic_config::Source config_source, utils::statistics::Storage &statistics_storage, testsuite::DumpControl &dump_control, DumpableEntity &dumpable)
 For internal use only.
 Dumper (Dumper &&)=delete
Dumperoperator= (Dumper &&)=delete
const std::string & Name () const
std::optional< TimePoint > ReadDump ()
 Read data from a dump, if any. More...
void WriteDumpSyncDebug ()
 Forces the Dumper to write a dump synchronously. More...
void ReadDumpDebug ()
 Forces the Dumper to read from a dump synchronously. More...
void OnUpdateCompleted ()
 Notifies the Dumper of an update in the DumpableEntity More...
void OnUpdateCompleted (TimePoint update_time, UpdateType update_type)
void CancelWriteTaskAndWait ()
 Cancel and wait for the task running background writes. Also disables operations via testsuite dump control. More...

Static Public Member Functions

static yaml_config::Schema GetStaticConfigSchema ()
 Returns the static config schema for a components::LoggableComponentBase with an added dump sub-section.

Detailed Description

Manages dumps of a cache-like component.

The class is thread-safe.

Used in components::CachingComponentBase.

Automatically subscribes to:

Dumps will be stored in {dump-root}/{dumper_name}, where dump-root is taken from components::DumpConfigurator.

Here, dumper_name is the name of the parent component.

Dynamic config

Static config

Name Type Description Default value
enable boolean Whether this Dumper should actually read and write dumps (required)
world-readable boolean If true, dumps are created with access 0444, otherwise with access 0400 (required)
format-version integer Allows to ignore dumps written with an obsolete format-version (required)
max-age optional string (duration) Overdue dumps are ignored null
max-count optional integer Old dumps over the limit are removed from disk 1
min-interval string (duration) WriteDumpAsync calls performed in a fast succession are ignored 0s
fs-task-processor string TaskProcessor for blocking disk IO fs-task-processor
encrypted boolean Whether to encrypt the dump false
first-update-mode string specifies whether required or best-effort first update will be used skip
first-update-type string specifies whether incremental and/or full first update will be used full

Sample usage

// NOLINTNEXTLINE(fuchsia-multiple-inheritance)
class SampleComponentWithDumps final : public components::LoggableComponentBase,
static constexpr auto kName = "component-with-dumps";
SampleComponentWithDumps(const components::ComponentConfig& config,
: LoggableComponentBase(config, context),
dumper_(config, context, *this) {
~SampleComponentWithDumps() override {
// This call is necessary in destructor. Otherwise, we could be writing data
// while the component is being destroyed.
std::string Get(const std::string& key) {
if (auto existing_value = data_.Get(key)) return *existing_value;
auto value = key + "foo";
data_.Emplace(key, value);
// Writes a new dump if enough time has passed since the last one
return value;
static yaml_config::Schema GetStaticConfigSchema() {
void GetAndWrite(dump::Writer& writer) const override {
void ReadAndSet(dump::Reader& reader) override {
using Map = std::unordered_map<std::string, std::shared_ptr<std::string>>;
dump::Dumper dumper_;
See also

Definition at line 96 of file dumper.hpp.

Constructor & Destructor Documentation

◆ Dumper()

dump::Dumper::Dumper ( const components::ComponentConfig config,
const components::ComponentContext context,
DumpableEntity dumpable 

The primary constructor for when Dumper is stored in a component.

dumpable must outlive this Dumper

Member Function Documentation

◆ CancelWriteTaskAndWait()

void dump::Dumper::CancelWriteTaskAndWait ( )

Cancel and wait for the task running background writes. Also disables operations via testsuite dump control.

CancelWriteTaskAndWait is automatically called in the destructor. This method must be called explicitly if the DumpableEntity may start its destruction before the Dumper is destroyed.

After calling this method, OnUpdateCompleted calls have no effect.

◆ OnUpdateCompleted()

void dump::Dumper::OnUpdateCompleted ( )

Notifies the Dumper of an update in the DumpableEntity

A dump will be written asynchronously as soon as:

  1. data update has been reported via OnUpdateCompleted since the last written dump,
  2. dumps are enabled in the dynamic config, and
  3. min-interval time has passed
This overload is more performant. The time written on the dump will be taken from the dump writing time.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

update_timeThe time at which the data has been guaranteed to be up-to-date
update_typeWhether the update modified the data or confirmed its actuality, UpdateType::kModified by default
This overload locks mutexes and should not be used in tight loops. On the other hand, it allows to exactly control the dump expiration.

◆ ReadDump()

std::optional< TimePoint > dump::Dumper::ReadDump ( )

Read data from a dump, if any.

Catches and logs any exceptions related to read operation failure
update_time of the loaded dump on success, null otherwise

◆ ReadDumpDebug()

void dump::Dumper::ReadDumpDebug ( )

Forces the Dumper to read from a dump synchronously.

std::exceptionif the Dumper failed to read a dump

◆ WriteDumpSyncDebug()

void dump::Dumper::WriteDumpSyncDebug ( )

Forces the Dumper to write a dump synchronously.

std::exceptionif the Dumper failed to write a dump

The documentation for this class was generated from the following file: