dump::Dumper Class Reference

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

Dumper Dynamic config

• USERVER_DUMPS

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::ComponentBase, private dump::DumpableEntity {
public:
    static constexpr std::string_view kName = "component-with-dumps";
 
    SampleComponentWithDumps(const components::ComponentConfig& config, const components::ComponentContext& context)
        : ComponentBase(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() { return dump::Dumper::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>());
    }
 
    rcu::RcuMap<std::string, std::string> data_;
    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
Dumper &	operator= (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::ComponentBase 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_time	The time at which the data has been guaranteed to be up-to-date
update_type	Whether 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::exception

if the Dumper failed to read a dump

WriteDumpSyncDebug()

void dump::Dumper::WriteDumpSyncDebug

(

)

Forces the Dumper to write a dump synchronously.

Exceptions

std::exception

if the Dumper failed to write a dump

---

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

• userver/dump/dumper.hpp