PMDA++
0.4.4
Header-only C++ library for writing PCP PMDAs
|
Abstract base class for implementing PCP PMDAs. More...
#include <pmda.hpp>
Classes | |
struct | fetch_value_result |
Struct returned by the fetch_value function. More... | |
struct | metric_id |
Indentifies a metric to be fetched. More... | |
Static Public Member Functions | |
template<class Agent > | |
static void | init_dso (pmdaInterface *const interface) |
Initialize PCP's DSO interface for a PMDA. More... | |
template<class Agent > | |
static int | run_daemon (const int argc, char *const argv[]) |
Run a PMDA in PCP's daemon mode. More... | |
Protected Types | |
typedef std::vector< std::string > | string_vector |
A simple vector of strings. More... | |
Protected Member Functions | |
virtual | ~pmda () |
Destructor. More... | |
virtual std::string | get_config_file_pathname () const |
Get the default path to this PMDA's optional configuration file. More... | |
virtual std::string | get_help_text_pathname () const |
Get the default path to this PMDA's optional help texts file. More... | |
virtual std::string | get_log_file_pathname () const |
Get the default path to this PMDA's log file. More... | |
virtual std::string | get_pmda_name () const =0 |
Get this PMDA's name. More... | |
virtual int | get_default_pmda_domain_number () const =0 |
Get this PMDA's default performance metrics domain number. More... | |
virtual std::string | get_pmda_version () const |
Get this PMDA's version string. More... | |
virtual void | run_daemon (const int argc, char *const argv[]) |
Run this daemon. More... | |
virtual bool | parse_command_line (const int argc, const char *const argv[], pmdaInterface &interface) |
Parse command line options. More... | |
virtual bool | parse_command_line (const int argc, const char *const argv[], pmdaInterface &interface, boost::program_options::variables_map &options) |
Parse command line options. More... | |
virtual boost::program_options::options_description | pcp_builtin_options () const |
Get a list of command line options built into the PCP libraries. More... | |
virtual boost::program_options::options_description | get_supported_options () const |
Get a list of command line options supported by this PMDA. More... | |
virtual boost::program_options::options_description | get_supported_hidden_options () const |
Get a list of hidden supported command line options. More... | |
virtual boost::program_options::positional_options_description | get_supported_positional_options () |
Get a list of supported positional options. More... | |
virtual void | display_help (const std::string &program_name) const |
Display a help message. More... | |
virtual void | display_version () const |
Display a version message. More... | |
virtual std::string | get_usage (const std::string &program_name) const |
Get a usage syntax string. More... | |
virtual void | initialize_dso (pmdaInterface &interface) |
Initialise a DSO interface with this PMDA. More... | |
virtual void | initialize_pmda (pmdaInterface &interface) |
Initialise this PMDA. More... | |
virtual pcp::metrics_description | get_supported_metrics ()=0 |
Get descriptions of all of the metrics supported by this PMDA. More... | |
virtual void | begin_fetch_values () |
Begin fetching values. More... | |
virtual fetch_value_result | fetch_value (const metric_id &metric)=0 |
Fetch an individual metric value. More... | |
virtual void | store_value (const metric_id &metric, const int &value) |
Store an in situ value. More... | |
virtual void | store_value (const metric_id &metric, const pmValueBlock *const value) |
Store an ex situ value. More... | |
virtual int | on_desc (pmID pmid, pmDesc *desc, pmdaExt *pmda) |
Return the metric desciption. More... | |
virtual int | on_fetch (int numpmid, pmID *pmidlist, pmResult **resp, pmdaExt *pmda) |
Resize the pmResult and call e_callback in the pmdaExt structure for each metric instance required by the profile. More... | |
virtual int | on_fetch_callback (pmdaMetric *mdesc, unsigned int inst, pmAtomValue *avp) |
Fetch the value of a single metric instance. More... | |
virtual int | on_instance (pmInDom indom, int inst, char *name, __pmInResult **result, pmdaExt *pmda) |
Return description of instances and instance domains. More... | |
virtual int | on_profile (__pmProfile *prof, pmdaExt *pmda) |
Store the instance profile away for the next fetch. More... | |
virtual int | on_store (pmResult *result, pmdaExt *pmda) |
Store a value into a metric. More... | |
virtual int | on_text (int ident, int type, char **buffer, pmdaExt *pmda) |
Return the help text for the metric. More... | |
virtual void | set_callbacks (pmdaInterface &interface) |
Set static callbacks on a PMDA interface. More... | |
Static Protected Member Functions | |
static pmda * | get_instance () |
Get the single PMDA instance. More... | |
static pmda * | set_instance (pmda *const new_instance) |
Set the single PMDA instance. More... | |
static void | check_conflicting_options (const boost::program_options::variables_map &options_map, const std::string &option1, const std::string &option2) |
Check for conflicting command line options. More... | |
Protected Attributes | |
metrics_description | supported_metrics |
|
protected |
|
inlineprotectedvirtual |
|
inlineprotectedvirtual |
Begin fetching values.
Derived classes may override this function to perform any actions they wish to perform at the start of each batch of fetch of metric values.
This base implementation performs no actions.
Definition at line 929 of file pmda.hpp.
References fetch_value().
Referenced by on_fetch().
|
inlinestaticprotected |
Check for conflicting command line options.
This convenience function can be used to check, in a standardised way, that two mutually exclusive options are not both set.
options_map | Parsed command line options. |
option1 | The first of two options that are mutually exclusive. |
option2 | The second of two options that are mutually exclusive. |
boost::program_options::error | If both option1 and option2 are set, and neither were defaulted. |
|
inlineprotectedvirtual |
Display a help message.
This function is called if the –help command line option was given.
Derived classes may override this function to customise the help text output.
program_name | The program name to include in the help message. |
Definition at line 747 of file pmda.hpp.
References get_supported_options(), and get_usage().
Referenced by parse_command_line().
|
inlineprotectedvirtual |
Display a version message.
This function is called if the –version command line option was given.
Derived classes may override this function to customise the version text output.
Definition at line 766 of file pmda.hpp.
References get_pmda_name(), get_pmda_version(), and PCP_CPP_PMDA_INTERFACE_VERSION.
Referenced by parse_command_line().
|
protectedpure virtual |
Fetch an individual metric value.
Derived classes must implment this function to fetch individual metric values.
If the requested metric value is not found, or some other error occurs, implementations should throw an appropriate pcp::exception, such as pcp::exception(PMDA_FETCH_NOVALUES)
.
Otherwise, the a valid atom value should be returned, encapsulated in a fetch_value_result struct. Typically the code
value of the returned struct should be left as PMDA_FETCH_STATIC
. However, advanced PMDAs may use any of the PMDA_FETCH_*
constants, such as PMDA_FETCH_DYNAMIC
.
Note, implementations should not return PMDA_FETCH_NOVALUES
- in that case, they should throw pcp::exception(PMDA_FETCH_NOVALUES)
instead.
metric | The metric to fetch the value of. |
pcp::exception | on error, or if the requested metric is not currently available. |
Referenced by begin_fetch_values(), and on_fetch_callback().
|
inlineprotectedvirtual |
Get the default path to this PMDA's optional configuration file.
Derived classes may override this function to provide a custom path. The default is equivalent to $PCP_PMDAS_DIR/$PMDA_NAME/config.
Definition at line 202 of file pmda.hpp.
References get_pmda_name().
Referenced by get_supported_options().
|
protectedpure virtual |
Get this PMDA's default performance metrics domain number.
Derived classes must override this function to return the default domain number for this PMDA.
Unless the command line parsing functions are overridden, this class will allow this default PMDA domain number to be overridden via the -d or –domain (Boost only) command line options.
Referenced by get_log_file_pathname(), pcp_builtin_options(), run_daemon(), and set_callbacks().
|
inlineprotectedvirtual |
Get the default path to this PMDA's optional help texts file.
Derived classes may override this function to provide a custom path. The default is equivalent to $PCP_PMDAS_DIR/$PMDA_NAME/help.
Definition at line 217 of file pmda.hpp.
References get_pmda_name().
Referenced by initialize_dso(), pcp_builtin_options(), and run_daemon().
|
inlinestaticprotected |
Get the single PMDA instance.
NULL
.Definition at line 166 of file pmda.hpp.
Referenced by init_dso(), run_daemon(), and set_callbacks().
|
inlineprotectedvirtual |
Get the default path to this PMDA's log file.
Derived classes may override this function to provide a custom path. The default is equivalent to $PCP_PMCD_DIR/$PMDA_NAME.log.
Definition at line 231 of file pmda.hpp.
References get_default_pmda_domain_number(), and get_pmda_name().
Referenced by pcp_builtin_options(), and run_daemon().
|
protectedpure virtual |
Get this PMDA's name.
Derived classes must override this function to return the name of the PMDA.
Referenced by display_version(), get_config_file_pathname(), get_help_text_pathname(), get_log_file_pathname(), initialize_dso(), parse_command_line(), run_daemon(), and set_callbacks().
|
inlineprotectedvirtual |
Get this PMDA's version string.
Derived classes may override this function to return a custom version string to be included in messages such as the outpt of the –version command line option.
This base implementation returns an empty string.
Definition at line 276 of file pmda.hpp.
Referenced by display_version().
|
inlineprotectedvirtual |
Get a list of hidden supported command line options.
Hidden command line options behave just like their non-hidden veriety, except that they are not included in the output of the –help option.
This is allows derived classes to implement, for example, development only options or other options that would be confusing to end users, without necessary having to make the obvious.
This, of course, should be used sparingly.
This base implementation returns an empty list.
Definition at line 694 of file pmda.hpp.
Referenced by parse_command_line().
|
protectedpure virtual |
Get descriptions of all of the metrics supported by this PMDA.
Dervied classes must implement this function to define the metrics supported by this PMDA.
Referenced by initialize_pmda().
|
inlineprotectedvirtual |
Get a list of command line options supported by this PMDA.
This base implementation returns a set of options including options supported by the PCP libraries, as well as a number of custom options implemented by this pcp::pmda class (such as –help and –version).
Derived classes may override this function to add to, or even replace, the set of options supported by the derived PMDA.
Definition at line 651 of file pmda.hpp.
References get_config_file_pathname(), pcp_builtin_options(), PCP_CPP_BOOST_PO_IMPLICIT_VALUE, and PCP_CPP_BOOST_PO_VALUE_NAME.
Referenced by display_help(), parse_command_line(), and run_daemon().
|
inlineprotectedvirtual |
Get a list of supported positional options.
Derived classes may override this function to support positional options.
This base implementation returns an empty list.
Definition at line 708 of file pmda.hpp.
Referenced by parse_command_line().
|
inlineprotectedvirtual |
Get a usage syntax string.
This function returns a string defining the command line syntax. It is included, by default, in the text output of the –help command line option.
This base implementation returns a string like: program [options]
. But, for example, if a derived class made some options compulsory, and/or allowed position arguments, then that class would want to override this function to return something like: program --required-flag=arg [options] filename1 filename2
.
program_name | The name of the program to include in the syntax line. |
Definition at line 804 of file pmda.hpp.
Referenced by display_help().
|
inlinestatic |
Initialize PCP's DSO interface for a PMDA.
Example usage:
interface | PMDA interface point provided by PCP as part of the DSO initialisation process. |
Definition at line 60 of file pmda.hpp.
References get_instance(), initialize_dso(), and set_instance().
|
inlineprotectedvirtual |
Initialise a DSO interface with this PMDA.
interface | PMDA interface to initialise. |
pcp::exception | on error. |
Definition at line 816 of file pmda.hpp.
References get_help_text_pathname(), get_pmda_name(), initialize_pmda(), and PCP_CPP_PMDA_INTERFACE_VERSION.
Referenced by init_dso().
|
inlineprotectedvirtual |
Initialise this PMDA.
interface | PMDA interface to initialise. |
Definition at line 845 of file pmda.hpp.
References pcp::metric_description::domain, pcp::metric_cluster::get_cluster_id(), pcp::instance_domain::get_domain_id(), pcp::instance_domain::get_pm_instance_domain(), get_supported_metrics(), pcp::metric_description::opaque, set_callbacks(), and pcp::instance_domain::set_pm_instance_domain().
Referenced by initialize_dso(), and run_daemon().
|
inlineprotectedvirtual |
Return the metric desciption.
Definition at line 1036 of file pmda.hpp.
Referenced by set_callbacks().
|
inlineprotectedvirtual |
Resize the pmResult and call e_callback in the pmdaExt structure for each metric instance required by the profile.
Definition at line 1043 of file pmda.hpp.
References begin_fetch_values(), pcp::exception::error_code(), and pcp::exception::what().
Referenced by set_callbacks().
|
inlineprotectedvirtual |
Fetch the value of a single metric instance.
Definition at line 1056 of file pmda.hpp.
References pcp::pmda::fetch_value_result::atom, pcp::pmda::metric_id::cluster, pcp::pmda::fetch_value_result::code, pcp::exception::error_code(), fetch_value(), pcp::metric_description::type, and pcp::exception::what().
Referenced by set_callbacks().
|
inlineprotectedvirtual |
Return description of instances and instance domains.
Definition at line 1104 of file pmda.hpp.
Referenced by set_callbacks().
|
inlineprotectedvirtual |
Store the instance profile away for the next fetch.
Definition at line 1127 of file pmda.hpp.
Referenced by set_callbacks().
|
inlineprotectedvirtual |
Store a value into a metric.
Definition at line 1133 of file pmda.hpp.
References pcp::pmda::metric_id::cluster, pcp::exception::error_code(), pcp::metric_description::flags, pcp::storable_metric, store_value(), pcp::metric_description::type, and pcp::exception::what().
Referenced by set_callbacks().
|
inlineprotectedvirtual |
Return the help text for the metric.
Definition at line 1192 of file pmda.hpp.
References pcp::exception::error_code(), pcp::instance_info::short_description, pcp::metric_description::short_description, pcp::instance_info::verbose_description, pcp::metric_description::verbose_description, and pcp::exception::what().
Referenced by set_callbacks().
|
inlineprotectedvirtual |
Parse command line options.
Override this overload if you want to customise the command line parsing process, but don't want to access any of the parsed options explicitly.
Note, it's pretty unusual to want to do this. This overload is really here to maintain compatibility between the Boost and non-Boost implementations of parse_command_line.
argc | Argument count. |
argv | Argumnet vector. |
interface | PMDA interface. |
true
if the caller should continue to run the PMDA, else false
.pcp::exception | On error. |
boost::program_options::error | On parse error. |
Definition at line 455 of file pmda.hpp.
Referenced by run_daemon().
|
inlineprotectedvirtual |
Parse command line options.
Override this function to gain access explicit to the parsed command line options, if desired.
argc | Argument count. |
argv | Argumnet vector. |
interface | PMDA interface. |
options | The parsed program options. |
true
if the caller should continue to run the PMDA, else false
.pcp::exception | On error. |
boost::program_options::error | On parse error. |
Definition at line 479 of file pmda.hpp.
References display_help(), display_version(), get_pmda_name(), get_supported_hidden_options(), get_supported_options(), get_supported_positional_options(), and pcp::cache::store().
|
inlineprotectedvirtual |
Get a list of command line options built into the PCP libraries.
Definition at line 611 of file pmda.hpp.
References get_default_pmda_domain_number(), get_help_text_pathname(), get_log_file_pathname(), PCP_CPP_BOOST_PO_IMPLICIT_VALUE, and PCP_CPP_BOOST_PO_VALUE_NAME.
Referenced by get_supported_options(), and run_daemon().
|
inlinestatic |
Run a PMDA in PCP's daemon mode.
Example usage:
argc | Argument count. |
argv | Argument vector. |
Definition at line 91 of file pmda.hpp.
References get_instance(), run_daemon(), and set_instance().
Referenced by run_daemon().
|
inlineprotectedvirtual |
Run this daemon.
This function implements the main processing loop of the daemon-mode PMDA. It performs various initalisations such as parsing the command line options, then defers processing to the pmdaMain function.
argc | Argument count. |
argv | Argument vector. |
pcp::exception | On error. |
Definition at line 293 of file pmda.hpp.
References get_default_pmda_domain_number(), get_help_text_pathname(), get_log_file_pathname(), get_pmda_name(), get_supported_options(), initialize_pmda(), parse_command_line(), pcp_builtin_options(), PCP_CPP_PMDA_CONST_CHAR, and PCP_CPP_PMDA_INTERFACE_VERSION.
|
inlineprotectedvirtual |
Set static callbacks on a PMDA interface.
This function sets our static PMDA callback functions on the given pmdaInterface struct. These static callback functions then redirect all calls to the current singleton PMDA instance.
interface | The interface to set our callbacks on. |
Definition at line 1255 of file pmda.hpp.
References pcp::metric_description::domain, pcp::metric_cluster::get_cluster_id(), pcp::metric_cluster::get_cluster_name(), get_default_pmda_domain_number(), pcp::instance_domain::get_domain_id(), get_instance(), get_pmda_name(), pcp::metric_description::metric_name, on_desc(), on_fetch(), on_fetch_callback(), on_instance(), on_profile(), on_store(), on_text(), and pcp::type().
Referenced by initialize_pmda().
Set the single PMDA instance.
new_instance | The new instance to set. |
NULL
.Definition at line 185 of file pmda.hpp.
Referenced by init_dso(), and run_daemon().
|
inlineprotectedvirtual |
Store an in situ value.
Derived classes may override this function to allow PCP to request metric values to be stored.
This base implementation throws pcp::exception(PM_ERR_PERMISSION)
.
PCP_CPP_NO_ID_VALIDITY_CHECKS
has been defined, this function will not be called for any metric that did not include the storable_metric
flag in the get_supported_metrics result.metric | The metric to store. |
value | The value to store. |
pcp::exception | on error. |
Definition at line 975 of file pmda.hpp.
References PCP_CPP_UNUSED.
Referenced by on_store().
|
inlineprotectedvirtual |
Store an ex situ value.
Derived classes may override this function to allow PCP to request metric values to be stored.
This base implementation throws pcp::exception(PM_ERR_PERMISSION)
.
PCP_CPP_NO_ID_VALIDITY_CHECKS
has been defined, this function will not be called for any metric that did not include the storable_metric
flag in the get_supported_metrics result.metric | The metric to store. |
value | The value to store. |
pcp::exception | on error. |
Definition at line 999 of file pmda.hpp.
References PCP_CPP_UNUSED.
|
protected |