PMDA++  0.4.4
Header-only C++ library for writing PCP PMDAs
Classes | Static Public Member Functions | Protected Types | Protected Member Functions | Static Protected Member Functions | Protected Attributes | List of all members
pcp::pmda Class Referenceabstract

Abstract base class for implementing PCP PMDAs. More...

#include <pmda.hpp>

Collaboration diagram for pcp::pmda:
Collaboration graph
[legend]

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 pmdaget_instance ()
 Get the single PMDA instance. More...
 
static pmdaset_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
 

Detailed Description

Abstract base class for implementing PCP PMDAs.

Definition at line 37 of file pmda.hpp.

Member Typedef Documentation

◆ string_vector

typedef std::vector<std::string> pcp::pmda::string_vector
protected

A simple vector of strings.

Definition at line 146 of file pmda.hpp.

Constructor & Destructor Documentation

◆ ~pmda()

virtual pcp::pmda::~pmda ( )
inlineprotectedvirtual

Destructor.

Definition at line 151 of file pmda.hpp.

Member Function Documentation

◆ begin_fetch_values()

virtual void pcp::pmda::begin_fetch_values ( )
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().

◆ check_conflicting_options()

static void pcp::pmda::check_conflicting_options ( const boost::program_options::variables_map &  options_map,
const std::string &  option1,
const std::string &  option2 
)
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.

Parameters
options_mapParsed command line options.
option1The first of two options that are mutually exclusive.
option2The second of two options that are mutually exclusive.
Exceptions
boost::program_options::errorIf both option1 and option2 are set, and neither were defaulted.

Definition at line 726 of file pmda.hpp.

◆ display_help()

virtual void pcp::pmda::display_help ( const std::string &  program_name) const
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.

Parameters
program_nameThe 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().

◆ display_version()

virtual void pcp::pmda::display_version ( ) const
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.

See also
get_pmda_version

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().

◆ fetch_value()

virtual fetch_value_result pcp::pmda::fetch_value ( const metric_id metric)
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.

Parameters
metricThe metric to fetch the value of.
Exceptions
pcp::exceptionon error, or if the requested metric is not currently available.
Returns
The value of the requested metric.

Referenced by begin_fetch_values(), and on_fetch_callback().

◆ get_config_file_pathname()

virtual std::string pcp::pmda::get_config_file_pathname ( ) const
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.

Note
This function is only available if Boost support is enabled.
Returns
The path to this PMDA's optional configuration file.

Definition at line 202 of file pmda.hpp.

References get_pmda_name().

Referenced by get_supported_options().

◆ get_default_pmda_domain_number()

virtual int pcp::pmda::get_default_pmda_domain_number ( ) const
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.

Note
The PCP project maintains a list of standard PMIDs. You should normally avoid clashing with any of those.
Returns
This PMDA's default domain number.
See also
http://git.pcp.io/cgi-bin/gitweb.cgi?p=pcp/pcp.git;a=blob;f=src/pmns/stdpmid.pcp

Referenced by get_log_file_pathname(), pcp_builtin_options(), run_daemon(), and set_callbacks().

◆ get_help_text_pathname()

virtual std::string pcp::pmda::get_help_text_pathname ( ) const
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.

Returns
The path to this PMDA's optional help texts file.

Definition at line 217 of file pmda.hpp.

References get_pmda_name().

Referenced by initialize_dso(), pcp_builtin_options(), and run_daemon().

◆ get_instance()

static pmda* pcp::pmda::get_instance ( )
inlinestaticprotected

Get the single PMDA instance.

Returns
A pointer to the single PMDA instance, if set, otherwise NULL.
See also
set_instance

Definition at line 166 of file pmda.hpp.

Referenced by init_dso(), run_daemon(), and set_callbacks().

◆ get_log_file_pathname()

virtual std::string pcp::pmda::get_log_file_pathname ( ) const
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.

Returns
The path to this PMDA's log file.

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().

◆ get_pmda_name()

virtual std::string pcp::pmda::get_pmda_name ( ) const
protectedpure virtual

Get this PMDA's name.

Derived classes must override this function to return the name of the PMDA.

Returns
This PMDA's name.

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().

◆ get_pmda_version()

virtual std::string pcp::pmda::get_pmda_version ( ) const
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.

Returns
This PMDA's version string.

Definition at line 276 of file pmda.hpp.

Referenced by display_version().

◆ get_supported_hidden_options()

virtual boost::program_options::options_description pcp::pmda::get_supported_hidden_options ( ) const
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.

Returns
A list of command line options to support, but not advertise.

Definition at line 694 of file pmda.hpp.

Referenced by parse_command_line().

◆ get_supported_metrics()

virtual pcp::metrics_description pcp::pmda::get_supported_metrics ( )
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.

Returns
Descriptions of all of the metrics supported by this PMDA.

Referenced by initialize_pmda().

◆ get_supported_options()

virtual boost::program_options::options_description pcp::pmda::get_supported_options ( ) const
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.

Returns
A list of command line options supported by this 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().

◆ get_supported_positional_options()

virtual boost::program_options::positional_options_description pcp::pmda::get_supported_positional_options ( )
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.

Returns
A list of supported positional options.

Definition at line 708 of file pmda.hpp.

Referenced by parse_command_line().

◆ get_usage()

virtual std::string pcp::pmda::get_usage ( const std::string &  program_name) const
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.

Parameters
program_nameThe name of the program to include in the syntax line.
Returns
A usage syntax line.
See also
display_help

Definition at line 804 of file pmda.hpp.

Referenced by display_help().

◆ init_dso()

template<class Agent >
static void pcp::pmda::init_dso ( pmdaInterface *const  interface)
inlinestatic

Initialize PCP's DSO interface for a PMDA.

Example usage:

class my_pmda : public pcp::pmda {
....
};
extern "C" void trivial_init(pmdaInterface *interface)
{
pcp::pmda::init_dso<my_pmda>(interface);
}
Parameters
interfacePMDA 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().

◆ initialize_dso()

virtual void pcp::pmda::initialize_dso ( pmdaInterface &  interface)
inlineprotectedvirtual

Initialise a DSO interface with this PMDA.

Parameters
interfacePMDA interface to initialise.
Exceptions
pcp::exceptionon 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().

◆ initialize_pmda()

virtual void pcp::pmda::initialize_pmda ( pmdaInterface &  interface)
inlineprotectedvirtual

◆ on_desc()

virtual int pcp::pmda::on_desc ( pmID  pmid,
pmDesc *  desc,
pmdaExt *  pmda 
)
inlineprotectedvirtual

Return the metric desciption.

Definition at line 1036 of file pmda.hpp.

Referenced by set_callbacks().

◆ on_fetch()

virtual int pcp::pmda::on_fetch ( int  numpmid,
pmID *  pmidlist,
pmResult **  resp,
pmdaExt *  pmda 
)
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().

◆ on_fetch_callback()

virtual int pcp::pmda::on_fetch_callback ( pmdaMetric *  mdesc,
unsigned int  inst,
pmAtomValue *  avp 
)
inlineprotectedvirtual

◆ on_instance()

virtual int pcp::pmda::on_instance ( pmInDom  indom,
int  inst,
char *  name,
__pmInResult **  result,
pmdaExt *  pmda 
)
inlineprotectedvirtual

Return description of instances and instance domains.

Definition at line 1104 of file pmda.hpp.

Referenced by set_callbacks().

◆ on_profile()

virtual int pcp::pmda::on_profile ( __pmProfile *  prof,
pmdaExt *  pmda 
)
inlineprotectedvirtual

Store the instance profile away for the next fetch.

Definition at line 1127 of file pmda.hpp.

Referenced by set_callbacks().

◆ on_store()

virtual int pcp::pmda::on_store ( pmResult *  result,
pmdaExt *  pmda 
)
inlineprotectedvirtual

◆ on_text()

virtual int pcp::pmda::on_text ( int  ident,
int  type,
char **  buffer,
pmdaExt *  pmda 
)
inlineprotectedvirtual

◆ parse_command_line() [1/2]

virtual bool pcp::pmda::parse_command_line ( const int  argc,
const char *const  argv[],
pmdaInterface &  interface 
)
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.

Parameters
argcArgument count.
argvArgumnet vector.
interfacePMDA interface.
Returns
true if the caller should continue to run the PMDA, else false.
Exceptions
pcp::exceptionOn error.
boost::program_options::errorOn parse error.

Definition at line 455 of file pmda.hpp.

Referenced by run_daemon().

◆ parse_command_line() [2/2]

virtual bool pcp::pmda::parse_command_line ( const int  argc,
const char *const  argv[],
pmdaInterface &  interface,
boost::program_options::variables_map &  options 
)
inlineprotectedvirtual

Parse command line options.

Override this function to gain access explicit to the parsed command line options, if desired.

Parameters
argcArgument count.
argvArgumnet vector.
interfacePMDA interface.
optionsThe parsed program options.
Returns
true if the caller should continue to run the PMDA, else false.
Exceptions
pcp::exceptionOn error.
boost::program_options::errorOn 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().

◆ pcp_builtin_options()

virtual boost::program_options::options_description pcp::pmda::pcp_builtin_options ( ) const
inlineprotectedvirtual

Get a list of command line options built into the PCP libraries.

Returns
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().

◆ run_daemon() [1/2]

template<class Agent >
static int pcp::pmda::run_daemon ( const int  argc,
char *const  argv[] 
)
inlinestatic

Run a PMDA in PCP's daemon mode.

Example usage:

class my_pmda : public pcp::pmda {
....
};
int main(int argc, char *argv[])
{
return pcp::pmda::run_daemon<my_pmda>(argc, argv);
}
Parameters
argcArgument count.
argvArgument vector.
Returns
EXIT_SUCCESS on success, EXIT_FAILURE on error.

Definition at line 91 of file pmda.hpp.

References get_instance(), run_daemon(), and set_instance().

Referenced by run_daemon().

◆ run_daemon() [2/2]

virtual void pcp::pmda::run_daemon ( const int  argc,
char *const  argv[] 
)
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.

Parameters
argcArgument count.
argvArgument vector.
Exceptions
pcp::exceptionOn 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.

◆ set_callbacks()

virtual void pcp::pmda::set_callbacks ( pmdaInterface &  interface)
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.

Parameters
interfaceThe 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_instance()

static pmda* pcp::pmda::set_instance ( pmda *const  new_instance)
inlinestaticprotected

Set the single PMDA instance.

Note
For performance reasons, this function is intentionally not thread safe. Nor does it need to be, given that the instance is set by either init_dso or run_daemon, long before any threads interested in this instance have been created.
Parameters
new_instanceThe new instance to set.
Returns
A pointer to the previous instance, if there was one, otherwise NULL.
See also
get_instance

Definition at line 185 of file pmda.hpp.

Referenced by init_dso(), and run_daemon().

◆ store_value() [1/2]

virtual void pcp::pmda::store_value ( const metric_id metric,
const int &  value 
)
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).

Note
Unless 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.
Parameters
metricThe metric to store.
valueThe value to store.
Exceptions
pcp::exceptionon error.

Definition at line 975 of file pmda.hpp.

References PCP_CPP_UNUSED.

Referenced by on_store().

◆ store_value() [2/2]

virtual void pcp::pmda::store_value ( const metric_id metric,
const pmValueBlock *const  value 
)
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).

Note
Unless 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.
Parameters
metricThe metric to store.
valueThe value to store.
Exceptions
pcp::exceptionon error.

Definition at line 999 of file pmda.hpp.

References PCP_CPP_UNUSED.

Member Data Documentation

◆ supported_metrics

metrics_description pcp::pmda::supported_metrics
protected

Description of all metrics supported by this PMDA. This is really just a cache of the value returned by get_supported_metrics during startup.

Definition at line 109 of file pmda.hpp.


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