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

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

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`
`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,
                                       private dump::DumpableEntity {
 public:
  static constexpr auto kName = "component-with-dumps";
 
  SampleComponentWithDumps(const components::ComponentConfig& config,
                           const components::ComponentContext& context)
      : 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() {
    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 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.

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:

data update has been reported via OnUpdateCompleted since the last written dump,
dumps are enabled in the dynamic config, and
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.