A Config_manager-related adapter-style class that manages a simple config setup involving a single (though arbitrarily complex) Option_set<>-ready raw value struct config store type Value_set, meant to be used only in static fashion. More...

#include <static_cfg_manager.hpp>

Inheritance diagram for flow::cfg::Static_config_manager< Value_set >:

[legend]

Collaboration diagram for flow::cfg::Static_config_manager< Value_set >:

[legend]

Public Types
enum	allow_invalid_defaults_tag_t { S_ALLOW_INVALID_DEFAULTS }
	Tag type: indicates an apply() method must allow invalid defaults and only complain if the config source does not explicitly supply a valid value. More...

using	Impl = Config_manager< Value_set, Null_value_set >
	The class we `private`ly subclass (in HAS-A fashion, not IS-A fashion). More...

Public Member Functions
	Static_config_manager (log::Logger *logger_ptr, util::String_view nickname, typename Option_set< Value_set >::Declare_options_func &&declare_opts_func_moved)
	Constructs a Static_config_manager ready to read static config via apply() and access it via values(). More...

bool	apply (const fs::path &cfg_path, const typename Final_validator_func< Value_set >::Type &final_validator_func)
	Invoke this after construction to load the permanent set of static config from config sources including a static config file. More...

bool	apply (allow_invalid_defaults_tag_t, const fs::path &cfg_path, const typename Final_validator_func< Value_set >::Type &final_validator_func)
	Identical to similar apply() overload without allow_invalid_defaults_tag_t tag; but skips the stringent check on individual defaults' validity. More...

bool	apply (const fs::path &cfg_path)
	Equivalent to the other apply() but with no inter-option validation (meaning the per-option validation passed to constructor is sufficient). More...

bool	apply (allow_invalid_defaults_tag_t, const fs::path &cfg_path)
	Identical to similar apply() overload without allow_invalid_defaults_tag_t tag; but skips the stringent check on individual defaults' validity. More...

const Value_set &	values () const
	Returns (always the same) reference to the managed `Value_set` structure. More...

Related Functions
(Note that these are not member functions.)
template<typename Value_set >
std::ostream &	operator<< (std::ostream &os, const Static_config_manager< Value_set > &val)
	Serializes (briefly) a Static_config_manager to a standard output stream. More...

Related Functions inherited from flow::cfg::Config_manager< Value_set, Null_value_set >
std::ostream &	operator<< (std::ostream &os, const Config_manager< S_d_value_set... > &val)
	Serializes (briefly) a Config_manager to a standard output stream. More...

Additional Inherited Members
Private Types inherited from flow::cfg::Config_manager< Value_set, Null_value_set >
enum	allow_invalid_defaults_tag_t
	Tag type: indicates an `apply_()` method must allow* invalid defaults and only complain if the config source does not explicitly supply a valid value. More...

using	On_dynamic_change_func = Function< void()>
	Short-hand for a callback to execute on dynamic config change. More...

Private Member Functions inherited from flow::cfg::Config_manager< Value_set, Null_value_set >
	Config_manager (log::Logger *logger_ptr, util::String_view nickname, typename Option_set< S_d_value_set >::Declare_options_func &&... declare_opts_func_moved)
	Constructs a Config_manager ready to read initial config via `apply_*()` and other setup methods; and further capable of both static and dynamic config. More...

bool	apply_static (const fs::path &static_cfg_path, const typename Final_validator_func< Value_set >::Type &... final_validator_func, bool commit=true)
	Invoke this after construction to load the permanent set of static config from config sources including a static config file; if you are also using dynamic config, see apply_static_and_dynamic() as a potential alternative. More...

bool	apply_static (allow_invalid_defaults_tag_t, const fs::path &static_cfg_path, const typename Final_validator_func< Value_set >::Type &... final_validator_func, bool commit=true)
	Identical to apply_static() overload without allow_invalid_defaults_tag_t tag; but skips the stringent check on individual defaults' validity. More...

bool	apply_static_and_dynamic (const fs::path &cfg_path, const typename Final_validator_func< S_d_value_set >::Type &... final_validator_func, bool commit=true)
	If you use dynamic config, and you allow for initial values for dynamic options to be read from the same file as the static config values, then invoke this instead of apply_static(). More...

bool	apply_static_and_dynamic (allow_invalid_defaults_tag_t, const fs::path &cfg_path, const typename Final_validator_func< S_d_value_set >::Type &... final_validator_func, bool commit=true)
	Identical to apply_static_and_dynamic() overload without allow_invalid_defaults_tag_t tag; but skips the stringent check on individual defaults' validity. More...

bool	apply_dynamic (const fs::path &dynamic_cfg_path, const typename Final_validator_func< Value_set >::Type &... final_validator_func, bool commit=true)
	Load the first or subsequent set of dynamic config from config source including a dynamic config file. More...

bool	apply_dynamic (allow_invalid_defaults_tag_t, const fs::path &dynamic_cfg_path, const typename Final_validator_func< Value_set >::Type &... final_validator_func, bool commit=true)
	Identical to apply_dynamic() overload without allow_invalid_defaults_tag_t tag; except that – applicably only to the initial apply_dynamic() without a preceding apply_static_and_dynamic() – skips the stringent check on individual defaults' validity. More...

void	reject_candidates ()
	Cancel a not-yet-canonicalized (incomplete) multi-source update, if one is in progress. More...

void	all_static_values (const Value_set **... value_set_or_null) const
	Emit a pointer to each permanently set static config value set; the same pointers are emitted throughout for each of the S_N_S_VALUE_SETS static config slots. More...

void	all_static_values_candidates (const Value_set **... value_set_or_null) const
	Similar to all_static_values(), but if called from within a validator function passed to apply_static() or apply_static_and_dynamic(), then for any static value set for which values have been parsed and validated (but not yet applied) so far, a pointer to the parsed values candidate will be emitted instead. More...

const Value_set &	static_values (size_t s_value_set_idx) const
	Similar to all_static_values(), but obtains the static config in one specified slot as opposed to all of them. More...

const Value_set &	static_values_candidate (size_t s_value_set_idx) const
	Similar to static_values(), but if called from within a validator function passed to apply_static() or apply_static_and_dynamic(), then the parsed values candidate will be returned, instead, if values have been parsed and validated for the static value set but have not yet been applied. More...

void	all_dynamic_values (typename Value_set::Const_ptr *... value_set_or_null) const
	Obtain ref-counted pointers to each currently-canonical set of dynamic config; each pointed-at `struct` is set permanently; while another call may return a different pointer if config is changed dynamically in the meantime (for that slot). More...

Value_set::Const_ptr	dynamic_values (size_t d_value_set_idx) const
	Similar to all_dynamic_values() but obtains the dynamic config in one specified slot as opposed to all of them. More...

On_dynamic_change_func_handle	register_dynamic_change_listener (size_t d_value_set_idx, On_dynamic_change_func &&on_dynamic_change_func_moved)
	Saves the given callback; next time `apply_dynamic(commit = true)` or `apply_static_and_dynamic(commit = true)` detects at least one changed (or initially set) option value in the specified slot, it will execute this and any other previously registered such callbacks synchronously. More...

void	unregister_dynamic_change_listener (const On_dynamic_change_func_handle &handle)
	Remove a previously registered dynamic change callback. More...

void	state_to_ostream (std::ostream &os) const
	Prints a human-targeted long-form summary of our contents, doubling as a usage message and a dump of current values where applicable. More...

void	log_state (log::Sev sev=log::Sev::S_INFO) const
	Logs what state_to_ostream() would print. More...

void	help_to_ostream (std::ostream &os) const
	Prints a human-targeted long-form usage message that includes all options with their descriptions and defaults. More...

void	log_help (log::Sev sev=log::Sev::S_INFO) const
	Logs what help_to_ostream() would print. More...

Private Member Functions inherited from flow::log::Log_context
	Log_context (Logger *logger=0)
	Constructs Log_context by storing the given pointer to a Logger and a null Component. More...

template<typename Component_payload >
	Log_context (Logger *logger, Component_payload component_payload)
	Constructs Log_context by storing the given pointer to a Logger and a new Component storing the specified generically typed payload (an `enum` value). More...

	Log_context (const Log_context &src)
	Copy constructor that stores equal `Logger*` and Component values as the source. More...

	Log_context (Log_context &&src)
	Move constructor that makes this equal to `src`, while the latter becomes as-if default-constructed. More...

Log_context &	operator= (const Log_context &src)
	Assignment operator that behaves similarly to the copy constructor. More...

Log_context &	operator= (Log_context &&src)
	Move assignment operator that behaves similarly to the move constructor. More...

void	swap (Log_context &other)
	Swaps Logger pointers and Component objects held by `*this` and `other`. More...

Logger *	get_logger () const
	Returns the stored Logger pointer, particularly as many `FLOW_LOG_*()` macros expect. More...

const Component &	get_log_component () const
	Returns reference to the stored Component object, particularly as many `FLOW_LOG_*()` macros expect. More...

Private Attributes inherited from flow::cfg::Config_manager< Value_set, Null_value_set >
const std::string	m_nickname
	See `nickname` ctor arg. More...

Static Private Attributes inherited from flow::cfg::Config_manager< Value_set, Null_value_set >
static constexpr size_t	S_N_VALUE_SETS
	The number of template params in this Config_manager instantiation. It must be even and positive. More...

static constexpr size_t	S_N_S_VALUE_SETS
	The number of static value sets (including any `Null_value_set`s). More...

static constexpr size_t	S_N_D_VALUE_SETS
	The number of dynamic value sets (including any `Null_value_set`s). More...

Detailed Description

template<typename Value_set>
class flow::cfg::Static_config_manager< Value_set >

A Config_manager-related adapter-style class that manages a simple config setup involving a single (though arbitrarily complex) Option_set<>-ready raw value struct config store type Value_set, meant to be used only in static fashion.

That is to say, the parsed config values are not meant to be accessed while the config is being read from file.

If you desire dynamic config (which can be read from file(s) at any time), and/or you need to manage more than one config struct (e.g., you're controlling 2+ entirely separate modules), then please use Config_manager which supports all that. (You can also develop your own handling of Option_set<Value_set> instead. See Config_manager doc header.)

The life cycle and usage are simple. Define your Value_set (see Option_set doc header for formal requirements, but basically you'll need a struct, an option-defining function using FLOW_CFG_OPTION_SET_DECLARE_OPTION(), and possibly an inter-option validator function). Construct the Static_config_manager<Value_set>. Call apply() to read a file. (You can do this more than once, potentially for different files. As of this writing only files are supported, but adding command line parsing would be an incremental change.) Then, call values() to get the reference to the immutable parsed Value_set. This reference can be passed around the application; values() will always return the same reference. Technically you could call apply() even after using values(); but it is not thread-safe to do so while accessing config values which would change concurrently with no protection.

Also you may create a const (immutable) Static_config_manager via its constructor and then just use it to output a help message (log_help() or help_to_ostream()). This could be used with your program's --help option or similar, and that's it (no parsing takes place).

// Example of a Static_config_manager created just to log the help, and that's it.
flow::cfg::Static_config_manager<Static_value_set>
  (get_logger(), "cfg", &static_cfg_declare_opts)
  .log_help();

Note: Config_manager provides the optional commit == false mode in apply_static(); this enables the "multi-source parsing and source skipping" described in its doc header. Static_config_manager, to keep its mission simple, cuts off access to this feature, meaning implicitly it always takes commit to equal true. That is, it is expected you'll be loading static config from exactly one file/one apply() call per attempt. Your Final_validator_func::Type final_validator_func() should return either Final_validator_outcome::S_ACCEPT or Final_validator_outcome::S_FAIL. It can return Final_validator_outcome::S_SKIP, but that would mean apply() will return true (success) but simply no-op (not update the canonical config as returned by values()).

Rationale

Config_manager is in the author's opinion not difficult to use, but it does use template parameter packs (typename... Value_set), and its API can be somewhat difficult to grok when all you have is the aforementioned simple use case.

Template Parameters

Value_set The settings struct – see Option_set doc header for requirements.

Definition at line 79 of file static_cfg_manager.hpp.

Member Typedef Documentation

◆ Impl

template<typename Value_set >

using flow::cfg::Static_config_manager< Value_set >::Impl = Config_manager<Value_set, Null_value_set>

The class we privately subclass (in HAS-A fashion, not IS-A fashion).

It is public basically so that we can refer to it in various forwarding using method directives below.

Definition at line 100 of file static_cfg_manager.hpp.

Member Enumeration Documentation

◆ allow_invalid_defaults_tag_t

template<typename Value_set >

enum flow::cfg::Static_config_manager::allow_invalid_defaults_tag_t

Tag type: indicates an apply() method must allow invalid defaults and only complain if the config source does not explicitly supply a valid value.

Otherwise the defaults themselves are also stringently checked regardless of whether they are overridden. This setting applies only to individual-option-validators. Final_validator_func validation is orthogonal to this.

Enumerator
S_ALLOW_INVALID_DEFAULTS	Sole value for tag type allow_invalid_defaults_tag_t.

Definition at line 91 of file static_cfg_manager.hpp.

Constructor & Destructor Documentation

◆ Static_config_manager()

template<typename Value_set >

flow::cfg::Static_config_manager< Value_set >::Static_config_manager	(	log::Logger *	logger_ptr,
		util::String_view	nickname,
		typename Option_set< Value_set >::Declare_options_func &&	declare_opts_func_moved
	)

explicit

Constructs a Static_config_manager ready to read static config via apply() and access it via values().

Logging assumption

*logger_ptr is a standard logging arg. Note, though, that the class will assume that log verbosity may not have yet been configured – since this Static_config_manager may be the thing configuring it. Informal recommendations:

You should let through INFO and WARNING messages in *logger_ptr.
If you plan to use *this only for log_help() (such as in your --help implementation), you should not let through TRACE-or-more-verbose.
Once (and if) you engage any actual parsing (apply()), TRACE may be helpful in debugging as usual.

Parameters

logger_ptr	Logger to use for subsequently logging.
nickname	Brief string used for logging subsequently.
declare_opts_func_moved	The declare-options callback as required by `Option_set<Value_set>` constructor; see its doc header for instructions.

Definition at line 292 of file static_cfg_manager.hpp.

Member Function Documentation

◆ apply() [1/4]

template<typename Value_set >

bool flow::cfg::Static_config_manager< Value_set >::apply	(	allow_invalid_defaults_tag_t	,
		const fs::path &	cfg_path
	)

Identical to similar apply() overload without allow_invalid_defaults_tag_t tag; but skips the stringent check on individual defaults' validity.

See also: allow_invalid_defaults_tag_t doc header and/or return-value doc just below.

Parameters

cfg_path See other apply().

Returns: See other apply(). However the latter will return false if a default is invalid, even if file cfg_path explicitly sets it to a valid value. This tagged overload will not.

Definition at line 328 of file static_cfg_manager.hpp.

◆ apply() [2/4]

template<typename Value_set >

bool flow::cfg::Static_config_manager< Value_set >::apply	(	allow_invalid_defaults_tag_t	,
		const fs::path &	cfg_path,
		const typename Final_validator_func< Value_set >::Type &	final_validator_func
	)

Identical to similar apply() overload without allow_invalid_defaults_tag_t tag; but skips the stringent check on individual defaults' validity.

See also: allow_invalid_defaults_tag_t doc header and/or return-value doc just below.

Parameters

cfg_path	See other apply().
final_validator_func	See other apply().

Returns: See other apply(). However the latter will return false if a default is invalid, even if file cfg_path explicitly sets it to a valid value. This tagged overload will not.

Definition at line 314 of file static_cfg_manager.hpp.

◆ apply() [3/4]

template<typename Value_set >

bool flow::cfg::Static_config_manager< Value_set >::apply ( const fs::path & cfg_path )

Equivalent to the other apply() but with no inter-option validation (meaning the per-option validation passed to constructor is sufficient).

See also apply() overload with allow_invalid_defaults_tag_t tag.

Parameters

cfg_path File to read.

Returns: true if and only if successfully parsed config source(s) and validated all settings; and defaults were also all individually valid.

Definition at line 322 of file static_cfg_manager.hpp.

◆ apply() [4/4]

template<typename Value_set >

bool flow::cfg::Static_config_manager< Value_set >::apply	(	const fs::path &	cfg_path,
		const typename Final_validator_func< Value_set >::Type &	final_validator_func
	)

Invoke this after construction to load the permanent set of static config from config sources including a static config file.

See also apply() overload with allow_invalid_defaults_tag_t tag.

After this runs and succeeds, you may use values() to access the loaded values (but see notes on final_validator_func arg and return value, regarding Final_validator_outcome::S_SKIP w/r/t final_validator_func arg).

On failure returns false; else returns true. In the former case the overall state is equal to that at entry to the method. Tip: On failure you may want to exit program with error; or you can continue knowing that values() will return default values according to Value_set() no-arg ctor. WARNING(s) logged given failure.

Before apply(), or after it fails, the contents of what values() returns will be the defaults from your Value_set structure in its constructed state. This may or may not have utility depending on your application.

apply() will not be tolerant of unknown option names appearing in the config source.

Note: final_validator_func() can be made quite brief by using convenience macro FLOW_CFG_OPT_CHECK_ASSERT(). This will take care of most logging in most cases.

Todo:: Add support for command line as a config source in addition to file(s), for static config in cfg::Config_manager.

Parameters

cfg_path File to read.

final_validator_func If parsing and individual-option-validation succeed, the method shall return success if final_validator_func(V) returns Final_validator_outcome::S_ACCEPT or Final_validator_outcome::S_SKIP, where V is the parsed Value_set; and in the former case values() post-this-method will return V. Informally: Please place individual-option validation into FLOW_CFG_OPTION_SET_DECLARE_OPTION() invocations; only use final_validator_func() for internal consistency checks (if any). Informally: It is unlikely, with Static_config_manager, that it should return SKIP; that feature is only useful with the multi-file-update feature which is not accessible through Static_config_manager. See the note about this in our class doc header.

Returns: true if and only if successfully parsed config source and validated all settings including final_validator_func() != S_FAIL; and defaults were also all individually valid. If true, and final_validator_func() == S_ACCEPT, then values() shall return the parsed Value_set. If true, but final_validator_func() == S_SKIP, then values() shall return the default-cted Value_set

Definition at line 301 of file static_cfg_manager.hpp.

◆ values()

template<typename Value_set >

const Value_set & flow::cfg::Static_config_manager< Value_set >::values

Returns (always the same) reference to the managed Value_set structure.

Before successful apply() these values will be at their defaults. Tip: It should be sufficient to pass around only the const ref obtained here all around the app – no Value_set copying should be needed.

Returns: See above. To reiterate: always the same reference is returned.

Definition at line 334 of file static_cfg_manager.hpp.

Friends And Related Function Documentation

◆ operator<<()

template<typename Value_set >

std::ostream & operator<<	(	std::ostream &	os,
		const Static_config_manager< Value_set > &	val
	)

Template Parameters

Value_set See Static_config_manager doc header.

Parameters

os	Stream to which to serialize.
val	Value to serialize.

Returns: os.

Definition at line 340 of file static_cfg_manager.hpp.

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

cfg/cfg_manager_fwd.hpp
cfg/static_cfg_manager.hpp

Public Types

Public Member Functions

Related Functions

Additional Inherited Members

Detailed Description

Rationale

Member Typedef Documentation

◆ Impl

Member Enumeration Documentation

◆ allow_invalid_defaults_tag_t

Constructor & Destructor Documentation

◆ Static_config_manager()

Logging assumption

Member Function Documentation

◆ apply() [1/4]

◆ apply() [2/4]

◆ apply() [3/4]

◆ apply() [4/4]

◆ values()

Friends And Related Function Documentation

◆ operator<<()