dfx::Utils::SystemConfig Class Reference

System configuration registry with typed values, entry metadata, and change callbacks. More...

#include <dfx-utilities/SystemConfig.hpp>

Classes
struct	Entry
	Metadata and accessors for a single configuration entry. More...
struct	Value
	Variant type used to represent configuration values. More...

Public Types
using	StringList = std::vector<std::string>
using	Setter = std::move_only_function<void (Value)>
	Setter callable used by an entry to apply a new value. Stored as std::move_only_function, so it can capture move-only state.
using	Getter = std::move_only_function<Value ()>
	Getter callable used by an entry to retrieve the current value. Stored as std::move_only_function, so it can capture move-only state.
using	Callback = std::move_only_function<void (std::string_view, Value const &, Value const &)>
	Callback invoked when an entry changes.
using	Id = uint32_t
	Opaque identifier used to deregister callbacks.
using	Callbacks = std::unordered_map<Id, Callback>
	Mapping from callback id to callback implementation.

Public Member Functions
	SystemConfig (UnorderedStringMap< Value > cliOverride={})
	Construct an empty configuration registry.
	SystemConfig (fs::path const &path, UnorderedStringMap< Value > cliOverride={})
	Construct and load configuration from a file.
	~SystemConfig ()
	Destructor.
void	addEntry (std::string key, Value defaultValue, std::string description, Getter getter, Setter setter, bool readOnly=false)
	Add a configuration entry.
void	removeEntry (std::string_view key)
	Remove a configuration entry.
bool	hasEntry (std::string_view key) const
	Check whether an entry exists.
bool	isEntryReadOnly (std::string_view configKey) const
	Check whether an entry is read-only.
std::string	entryDescription (std::string_view configKey) const
	Get an entry's description.
Value	entryDefaultValue (std::string_view configKey) const
	Get an entry's default value.
Value	entryValue (std::string_view configKey) const
	Get an entry's current value via its getter.
void	setEntryValue (std::string_view configKey, Value newValue)
	Set an entry's value.
nlohmann::json	queryJson (std::string_view path) const
	Query a sub-section of the configuration as JSON.
std::unordered_map< std::string, Value >	allEntryValues () const
	Retrieve the current values for all registered entries.
void	loadConfig (fs::path const &path)
	Load (or reload) configuration values from a file.
fs::path const &	configPath () const noexcept
	Get the path of the latest configuration loaded.
Id	registerCallback (std::string_view configKey, Callback cb)
	Register a callback for a specific configuration key.
void	deregisterCallback (Id id)
	Deregister a callback by id.

Detailed Description

System configuration registry with typed values, entry metadata, and change callbacks.

The configuration holds a set of entries. Each entry provides:

• a default value,
• a human-readable description,
• a getter and setter supplied by the owning subsystem,
• an optional read-only flag.

Values are stored as Value, a small tagged union supporting boolean, integer, floating-point, and string types.

Setters are free to normalize, clamp, or reject values. A change is only considered effective if the value retrieved after applying the setter differs from the previous value. Callbacks are invoked only in that case.

CLI-provided overrides can be supplied at construction time and take precedence over defaults and file-loaded values.

Example usage

The following example registers a configuration entry controlling the size of a thread pool. The owning component provides both the getter and the setter, allowing it to validate and apply changes immediately:

sysConfig.addEntry(
    Keys::threadPoolSize,
    1,
    "Control the thread pool size. The thread pool will always contain at least 1 thread",
    [this] noexcept { return _threadPool.threadCount(); },
    [this](du::SystemConfig::Value value)
    {
        DFX_ASSERT(value.is_integer(), "The thread count value must be a valid integer");
 
        auto const threadCount = value.to_integer();
        DFX_ASSERT(threadCount >= 0, "The thread count must be >= 0. Got {}", threadCount);
 
        if (threadCount > _threadPool.threadCount())
            _threadPool.addThread(threadCount - _threadPool.threadCount());
        else
            _threadPool.removeThread(_threadPool.threadCount() - threadCount);
    }
);

In this example:

• The getter reflects the current runtime state.
• The setter validates the input and applies the change immediately.
• Invalid values are rejected via assertions.
• Callbacks (if registered) are only triggered when the effective thread count changes.

Note

Configuration entries do not store values internally; they delegate storage and validation entirely to the owning subsystem via getters and setters.

Member Typedef Documentation

Callback

using dfx::Utils::SystemConfig::Callback = std::move_only_function<void (std::string_view, Value const &, Value const &)>

Callback invoked when an entry changes.

Parameters

key	The configuration key that changed.
oldValue	Previous value.
newValue	New value.

Note

Callbacks are registered per key via registerCallback.

Callbacks

using dfx::Utils::SystemConfig::Callbacks = std::unordered_map<Id, Callback>

Mapping from callback id to callback implementation.

Getter

using dfx::Utils::SystemConfig::Getter = std::move_only_function<Value ()>

Getter callable used by an entry to retrieve the current value. Stored as std::move_only_function, so it can capture move-only state.

Id

using dfx::Utils::SystemConfig::Id = uint32_t

Opaque identifier used to deregister callbacks.

Setter

using dfx::Utils::SystemConfig::Setter = std::move_only_function<void (Value)>

Setter callable used by an entry to apply a new value. Stored as std::move_only_function, so it can capture move-only state.

Constructor & Destructor Documentation

SystemConfig() [1/2]

dfx::Utils::SystemConfig::SystemConfig ( UnorderedStringMap< Value > cliOverride = {} )

explicit

Construct an empty configuration registry.

Parameters

cliOverride

Optional key/value overrides (typically from CLI parsing).

Overrides provided here are stored and can be applied with higher priority than defaults and/or file-loaded values (depending on implementation).

SystemConfig() [2/2]

dfx::Utils::SystemConfig::SystemConfig ( fs::path const & path, UnorderedStringMap< Value > cliOverride = {} )

explicit

Construct and load configuration from a file.

Parameters

path	Path to the configuration file to load.
cliOverride	Optional key/value overrides (typically from CLI parsing).

Equivalent to constructing with overrides, then calling loadConfig.

~SystemConfig()

dfx::Utils::SystemConfig::~SystemConfig

(

)

Destructor.

Member Function Documentation

addEntry()

void dfx::Utils::SystemConfig::addEntry	(	std::string	key,
		Value	defaultValue,
		std::string	description,
		Getter	getter,
		Setter	setter,
		bool	readOnly = false )

Add a configuration entry.

Parameters

key	Entry key
defaultValue	Default value.
description	Human-readable description.
getter	Callable returning the current value.
setter	Callable applying a new value.
readOnly	If true, the entry is treated as read-only.

After registration, the entry can be queried with hasEntry and accessed with the various entry* methods. Setting a value via setEntryValue may trigger callbacks registered with registerCallback.

allEntryValues()

std::unordered_map< std::string, Value > dfx::Utils::SystemConfig::allEntryValues

(

)

const

Retrieve the current values for all registered entries.

Returns

A map of entry key to current value.

Values are obtained via each entry's getter.

configPath()

fs::path const & dfx::Utils::SystemConfig::configPath ( ) const

inlinenoexcept

Get the path of the latest configuration loaded.

deregisterCallback()

void dfx::Utils::SystemConfig::deregisterCallback

(

Id

id

)

Deregister a callback by id.

Parameters

id	Callback id previously returned by registerCallback.

Note

If id is unknown, this is a no-op

entryDefaultValue()

Value dfx::Utils::SystemConfig::entryDefaultValue ( std::string_view configKey ) const

inline

Get an entry's default value.

entryDescription()

std::string dfx::Utils::SystemConfig::entryDescription ( std::string_view configKey ) const

inline

Get an entry's description.

entryValue()

Value dfx::Utils::SystemConfig::entryValue ( std::string_view configKey ) const

inline

Get an entry's current value via its getter.

hasEntry()

bool dfx::Utils::SystemConfig::hasEntry

(

std::string_view

key

)

const

Check whether an entry exists.

isEntryReadOnly()

bool dfx::Utils::SystemConfig::isEntryReadOnly ( std::string_view configKey ) const

inline

Check whether an entry is read-only.

loadConfig()

void dfx::Utils::SystemConfig::loadConfig

(

fs::path const &

path

)

Load (or reload) configuration values from a file.

Parameters

path	Path to the configuration file.

queryJson()

nlohmann::json dfx::Utils::SystemConfig::queryJson

(

std::string_view

path

)

const

Query a sub-section of the configuration as JSON.

Parameters

path	TOML path (e.g., "plugins.info")

Returns

nlohmann::json object (object, array, or value) or a nlohmann::json::value_t::discarded type if the path doesn't exists.

registerCallback()

Id dfx::Utils::SystemConfig::registerCallback	(	std::string_view	configKey,
		Callback	cb )

Register a callback for a specific configuration key.

Parameters

configKey	Entry key to observe.
cb	Callback to invoke on changes.

Returns

An id that can be used with deregisterCallback.

removeEntry()

void dfx::Utils::SystemConfig::removeEntry

(

std::string_view

key

)

Remove a configuration entry.

Parameters

key	Key of the entry to remove.

After removal, querying the entry by key is invalid.

setEntryValue()

void dfx::Utils::SystemConfig::setEntryValue	(	std::string_view	configKey,
		Value	newValue )

Set an entry's value.

Parameters

configKey	Entry key.
newValue	New value to apply.

The update follows these steps:

1. The entry is looked up and asserted to not be read-only.
2. The current value is retrieved via the entry getter.
3. If the current value compares equal to newValue, the call is a no-op.
4. The setter is invoked with newValue.
5. The value is retrieved again via the getter.
6. If the value did not effectively change, the call is a no-op.
7. Registered callbacks for this key are invoked with the old and new values.

Callbacks are only triggered if the value effectively changes after the setter has been applied. This allows setters to clamp, normalize, or reject values silently.

Warning

Attempting to modify a read-only entry triggers an exception.

---

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

• lib/dfx-utilities/SystemConfig.hpp