The configuration mechanism consists of the following concepts:
Specification
Specifies the available configuration parameters of a module,
their names and their types.
Param
Specifies a parameter, its name and its type.
Type
Specifies the type of a configuration parameters; Bool, Size,
Count, etc.
Configuration
Specifies the configuration values of a particular instance of
the module. Configuration walks hand in hand with Specification,
the latter specifies what the former should contain.
A Specification is capable of configuring a Configuration from a
MXS_CONFIG_PARAMETER, checking in the process that all parameters
are of the correct type and that the required parameters are present.
A Specification is capable of persisting itself so that it later
can be read back.
The mechanism is closed for modification but open for extension in
the sense that if a module requires a custom parameter, all it needs
to do is to derive one class from Param and another from Type.
The canonical way for using this mechanism is as follows. Consider
a module xyx that has three parameters; a parameter called
"enabled" that is of boolean type, a parameter called "period"
that is of duration type, and a parameter "cache" that is of
size type. That would be declared as follows:
// xyz.hh
class XYZSession;
class XYZ : public maxscale::Filter<XYZ, XYZSession>
{
public:
static XYZ* create(const char* zName, MXS_CONFIG_PARAMETER* pParams);
private:
XYZ();
static config::Specification s_specification;
static config::ParamBool s_enabled;
static config::ParamDuration<std::chrono::seconds> s_period;
static config::ParamSize s_cache;
config::Configuration m_configuration;
config::Bool m_enabled;
config::Duration<std::chrono::seconds> m_period;
config::Size m_cache;
};
// xyz.cc
config::Specification XYZ::s_specification(MXS_MODULE_NAME);
config::ParamBool XYZ::s_enabled(
&s_specification,
"enabled",
"Specifies whether ... should be enabled or not."
);
config::ParamDuration<std::chrono::seconds> XYZ::s_period(
&s_specification,
"period",
"Specifies the period. Rounded to the nearest second."
);
config::ParamSize XYZ::s_cache(
&s_specification,
"cache",
"Specifies the size of the internal cache."
);
XYZ::XYZ()
: m_configuration(&s_specification)
, m_enabled(&m_configuration, &s_enabled)
, m_period(&m_configuration, &s_period)
, m_cache(&m_configuration, &s_cache)
{
}
XYZ* XYZ::create(const char* zName, MXS_CONFIG_PARAMETER* pParams)
{
XYZ* pXyz = new XYZ;
if (!s_specification.configure(pXyz->m_configuration, pParams))
{
delete pXyz;
pXyz = nullptr;
}
return pXyz;
}
This way the state is encapsulated in the object and the required changes
are done in one place. This makes the code reusable across all functions
making it easier to implement better monitor alteration code.
Reactivating monitors shouldn't be done as it's simpler to actually
destroy and create a new one. The performance of reactivation is
insignificant compared to the possible inconsistency problems it allows.
The helper function makes it easier to convert enum values at runtime to
their integer representation. Also changed the configuration processing
code to use the new function.
Although the default value is the maximum value of a signed 32-bit
integer, the value is stored as a 64-bit integer. The integer type
conversion functions return 64-bit values so storing it as one makes
sense.
Currently values higher than the default are allowed but the accepted
range of input should be restricted in the future.
The parameters are now written in the order they appear in the module
parameter definitions. Also enabled a previously disabled part in
server unit test.
Previously, runtime monitor modifications could directly alter monitor fields,
which could leave the text-form parameters and reality out-of-sync. Also,
the configure-function was not called for the entire monitor-object, only the
module-implementation.
Now, all modifications go through the overridden configure-function, which calls the
base-class function. As most configuration changes are given in text-form, this
removes the need for specific setters. The only exceptions are the server add/remove
operations, which must modify the text-form serverlist.
Added a new module parameter type to be used for parameters
that specify a duration. With the suffixes 'h', 'm', 's' and
'ms' the duration can be specified in hours, minutes, seconds
or milliseconds, respectively.
Irrespective of how the duration is specified, it is always
returned as milliseconds.
For backward compatibility, when a duration value is read it must
be specifed how a value *not* defined using a suffix should be
interpreted; as seconds or milliseconds.
value = param->get_duration(name, mxs::config::INTERPRET_AS_SECONDS);
When the servers of a service are defined by a monitor, then
at startup all servers of the monitor should be added to relevant
services. Likewise, when a server is added to or removed from a
monitor at runtime, those changes should affect services as well.
However, whether that should happen or not depends upon the monitor.
In the case of the Clustrix monitor this should not happen as it
adds and removes servers depending on the runtime state of the
Clustrix cluster.
If the servers of a service are defined by a monitor (the config
has 'cluster=SomeMonitor'), then the addition of a server to a
a monitor should lead to that server being added to the service.
The services whose servers are defined using a monitor, will
now be populated from the monitor.
Note, no consideration has yet been given to runtime changes.
The manipulation functions are currently static so that the container can be initialized
if required. This will be fixed later.
The new functions are taken into use in monitor management.
Replaces uses of config_get_param() in modules either with contains()
or get_string(). The config_get_param() is moved to internal headers,
as it allows seeing inside a config setting.
Since the settings are now protected fields, all related functions were
moved inside the monitor class. mon_ping_or_connect_to_db() is now a method
of MXS_MONITORED_SERVER. The connection settings class is defined inside the
server since that is the class actually using the settings.
The class MonitorManager contains monitor-related functions that should not
be called from modules. MonitorManager can access private fields and methods
of the monitor.
MaxScale server objects are now created for all Clustrix nodes.
Currently the name is "Clustrix-Server-N" where N is the number
of the node.
The server is created using runtime_create_server() that has been
modified so that it optionally will not persist the created server.
That is probably just a temporary solution as a monitor should not
need to include .../core/internal-stuff.
