Github   Telegram
Loading...
Searching...
No Matches
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
 
void WriteDumpAsync ()
 Write data to a dump if data has been modified. More...
 
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 (TimePoint update_time, UpdateType update_type)
 Notifies the Dumper of an update in the DumpableEntity More...
 
void SetModifiedAndWriteAsync ()
 Equivalent to OnUpdateCompleted(now, true) +WriteDumpAsync()`.
 
void CancelWriteTaskAndWait ()
 Cancel and wait for the task launched by WriteDumpAsync, if any. More...
 

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,
public:
static constexpr auto 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_.SetModifiedAndWriteAsync();
return value;
}
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 95 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.

Note
dumpable must outlive this Dumper

Member Function Documentation

◆ CancelWriteTaskAndWait()

void dump::Dumper::CancelWriteTaskAndWait ( )

Cancel and wait for the task launched by WriteDumpAsync, if any.

The task is automatically cancelled and waited for in the destructor. This method must be called if the DumpableEntity may start its destruction before the Dumper is destroyed.

◆ OnUpdateCompleted()

void dump::Dumper::OnUpdateCompleted ( TimePoint  update_time,
UpdateType  update_type 
)

Notifies the Dumper of an update in the DumpableEntity

Must be called at some point before a WriteDumpAsync call, otherwise no dump will be written.

◆ 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

◆ WriteDumpAsync()

void dump::Dumper::WriteDumpAsync ( )

Write data to a dump if data has been modified.

Dumper has NO PeriodicTasks running in the background. All writes must be performed explicitly by the user.

The dump is only written if:

  1. data update has been reported via OnUpdateCompleted since the last written dump
  2. dumps are currently enabled
  3. min-interval time has passed

It is a good idea to call WriteDumpAsync after each update.

Note
Catches and logs any exceptions related to write operation failure
See also
OnUpdateCompleted

◆ 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: