nx_metadata_sdk  1.0
Metadata SDK
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
nx::kit::IniConfig Class Reference

#include <ini_config.h>

Inheritance diagram for nx::kit::IniConfig:
nx::vms_server_plugins::analytics::stub::best_shots::Ini nx::vms_server_plugins::analytics::stub::custom_metadata::Ini nx::vms_server_plugins::analytics::stub::deprecated_object_detection::Ini nx::vms_server_plugins::analytics::stub::diagnostic_events::Ini nx::vms_server_plugins::analytics::stub::events::Ini nx::vms_server_plugins::analytics::stub::motion_metadata::Ini nx::vms_server_plugins::analytics::stub::object_actions::Ini nx::vms_server_plugins::analytics::stub::object_detection::Ini nx::vms_server_plugins::analytics::stub::object_streamer::Ini nx::vms_server_plugins::analytics::stub::roi::Ini nx::vms_server_plugins::analytics::stub::sdk_features::Ini nx::vms_server_plugins::analytics::stub::settings::Ini nx::vms_server_plugins::analytics::stub::special_objects::Ini nx::vms_server_plugins::analytics::stub::taxonomy_features::Ini nx::vms_server_plugins::analytics::stub::video_frames::Ini SavedIni TestIni

Classes

class  Impl
 

Public Types

enum  ParamType { ParamType::boolean, ParamType::string, ParamType::integer, ParamType::float_ }
 

Public Member Functions

 IniConfig (const char *iniFile)
 
 IniConfig (const IniConfig &)=delete
 
 IniConfig (IniConfig &&)=delete
 
IniConfigoperator= (const IniConfig &)=delete
 
IniConfigoperator= (IniConfig &&)=delete
 
const char * iniFile () const
 
const char * iniFilePath () const
 
void reload ()
 
bool getParamTypeAndValue (const char *paramName, ParamType *outType, const void **outData) const
 
 Tweaks ()
 
 Tweaks (const Tweaks &)=delete
 
 Tweaks (Tweaks &&)=delete
 
Tweaks & operator= (const Tweaks &)=delete
 
Tweaks & operator= (Tweaks &&)=delete
 
template<typename T >
void set (const T *field, T newValue)
 

Static Public Member Functions

static bool isEnabled ()
 
static void setEnabled (bool value)
 
static void setOutput (std::ostream *output)
 
static const char * iniFilesDir ()
 
static void setIniFilesDir (const char *iniFilesDir)
 

Protected Member Functions

bool regBoolParam (const bool *pValue, bool defaultValue, const char *paramName, const char *description)
 
int regIntParam (const int *pValue, int defaultValue, const char *paramName, const char *description)
 
const char * regStringParam (const char *const *pValue, const char *defaultValue, const char *paramName, const char *description)
 
float regFloatParam (const float *pValue, float defaultValue, const char *paramName, const char *description)
 

Detailed Description

Mechanism for configuration variables that can alter the behavior of the code for the purpose of debugging and experimenting, with very little performance overhead. The default (initial) values are defined in the code and lead to the nominal behavior, which can be overridden by creating .ini files (with name=value lines) in the directory determined by the platform:

Each derived class represents a dedicated .ini file. If, on attempt to load a file, it is found empty, the file is filled with default values and descriptions. The names of .ini files and their values are printed to stderr (configurable), overridden values marked with "*".

The format of a .ini file is as follows: lines beginning with # are ignored (treated as comments); whitespace around the name, the equals sign, and the value is ignored; the value can be surrounded with quotes ("), in which case it is parsed using a C-style-escaping, supporting concatenation of consecutive enquoted strings, but not supporting \uXXXX and \UXXXXXXXX.

Usage example, .h file:

    struct Ini: nx::kit::IniConfig
    {
        // NOTE: Omit `reload();` if load-on-start is not needed.
        Ini(): IniConfig("my_module.ini") { reload(); }
        NX_INI_FLAG(0, myFlag, "Here 0 stands for 'false' as the default value.");
        NX_INI_INT(7, myInt, "Here 7 is the default value.");
        NX_INI_STRING("Default value", myStr, "Description.");
        NX_INI_FLOAT(1.0, myFloat, "Here 1.0 is the default value.");
    };
    Ini& ini();

Usage example, .cpp file:

    Ini& ini()
    {
        static Ini ini;
        return ini;
    }

In the code, use ini().<param-name> to access the values. Call ini().reload() when needed, e.g. when certain activity starts or at regular intervals.

NOTE: The function that owns an IniConfig instance can be placed in the header file as 'inline', but it is safe only when the header is local to a single dynamic library or executable. Otherwise (if the header is included into more than one dynamic library or executable), due to compiler/linker limitations, such variables may have duplicate instances, thus, the function definition must be moved to a .cpp.

Allows to tweak IniConfig values for the duration defined by this object life time. Re-reading the values is disabled while at least one Tweaks instance exists. Intended for tests.

Usage:

{
IniConfig::Tweaks tweaks;
tweaks.set(&ini().parameter, value);
// The value will be altered up to the end of this scope.
}

Member Enumeration Documentation

◆ ParamType

Enumerator
boolean 

bool

string 

const char*

integer 

int

float_ 

float

Constructor & Destructor Documentation

◆ IniConfig()

nx::kit::IniConfig::IniConfig ( const char *  iniFile)
explicit
Parameters
iniFileName of .ini file without a path but including ".ini" suffix.

Member Function Documentation

◆ getParamTypeAndValue()

bool nx::kit::IniConfig::getParamTypeAndValue ( const char *  paramName,
ParamType outType,
const void **  outData 
) const

Get parameter type and value by its name.

Returns
True on success, false if the parameter with the specified name isn't found.

◆ iniFile()

const char * nx::kit::IniConfig::iniFile ( ) const
Returns
Stored copy of the string supplied to the ctor.

◆ iniFilePath()

const char * nx::kit::IniConfig::iniFilePath ( ) const

◆ iniFilesDir()

const char * nx::kit::IniConfig::iniFilesDir ( )
static
Returns
Currently used path to .ini files, including the trailing slash or backslash.

◆ isEnabled()

bool nx::kit::IniConfig::isEnabled ( )
static
Returns
Whether reading .ini files is enabled. If disabled, the values are frozen at defaults. Enabled by default, can be disabled by setEnabled(false) or by defining a macro at compiling ini_config.cpp: -DNX_INI_CONFIG_DISABLED to minimize performance overhead.

◆ reload()

void nx::kit::IniConfig::reload ( )

Reload values from .ini file, logging the values first time, or if changed.

Can be called from any thread. Creates a fence, so the values in the fields are available to other threads immediately after reloading finishes. The fields themselves, though not declared atomic, are 32-bit values and thus will always be updated atomically.

◆ setIniFilesDir()

void nx::kit::IniConfig::setIniFilesDir ( const char *  iniFilesDir)
static

Use the specified directory for .ini files. If iniFilesDir is null or empty, and also before this call, a platform-dependent directory is used (described in this class comment), which can be changed defining a macro at compiling ini_config.cpp: -DNX_INI_CONFIG_DEFAULT_INI_FILES_DIR=<enquoted-path-with-trailing-slash-or-backslash>

Parameters
iniFilesDirShould include the trailing slash or backslash.

◆ setOutput()

void nx::kit::IniConfig::setOutput ( std::ostream *  output)
static

Change the output stream, affecting all instances, null means silent. Before this call, all output goes to std::cerr, which can be changed defining a macro at compiling ini_config.cpp: -DNX_INI_CONFIG_DEFAULT_OUTPUT=<stream-address>, where <stream-address> can be e.g. '&std::cout', or 'nullptr' for no output.


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