userver: dump::Dumper Class Reference
Loading...
Searching...
No Matches
dump::Dumper Class Referencefinal

#include <userver/dump/dumper.hpp>

Detailed Description

Manages dumps of a cache-like component.

The class is thread-safe.

Used in components::CachingComponentBase.

Automatically subscribes to:

  • dynamic config updates from USERVER_DUMPS under dumper_name
  • statistics under cache.{dumper_name}.dump

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

Sample usage

// NOLINTNEXTLINE(fuchsia-multiple-inheritance)
class SampleComponentWithDumps final : public components::LoggableComponentBase,
public:
static constexpr std::string_view kName = "component-with-dumps";
SampleComponentWithDumps(const components::ComponentConfig& config,
: LoggableComponentBase(config, context),
dumper_(config, context, *this) {
dumper_.ReadDump();
}
~SampleComponentWithDumps() override {
// This call is necessary in destructor. Otherwise, we could be writing data
// while the component is being destroyed.
dumper_.CancelWriteTaskAndWait();
}
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
dumper_.OnUpdateCompleted();
return value;
}
static yaml_config::Schema GetStaticConfigSchema() {
}
private:
void GetAndWrite(dump::Writer& writer) const override {
writer.Write(data_.GetSnapshot());
}
void ReadAndSet(dump::Reader& reader) override {
using Map = std::unordered_map<std::string, std::shared_ptr<std::string>>;
data_.Assign(reader.Read<Map>());
}
dump::Dumper dumper_;
};
See also
components::DumpConfigurator

Definition at line 94 of file 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.
 
 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.
 
void WriteDumpSyncDebug ()
 Forces the Dumper to write a dump synchronously.
 
void ReadDumpDebug ()
 Forces the Dumper to read from a dump synchronously.
 
void OnUpdateCompleted ()
 Notifies the Dumper of an update in the DumpableEntity
 
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.
 

Static Public Member Functions

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

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.

Note
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
Note
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.

Parameters
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
Note
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.

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

◆ ReadDumpDebug()

void dump::Dumper::ReadDumpDebug ( )

Forces the Dumper to read from a dump synchronously.

Exceptions
std::exceptionif the Dumper failed to read a dump

◆ WriteDumpSyncDebug()

void dump::Dumper::WriteDumpSyncDebug ( )

Forces the Dumper to write a dump synchronously.

Exceptions
std::exceptionif the Dumper failed to write a dump

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