NAME

       QmcMetric - container for a metric and all its values

C++ SYNOPSIS

       #include <pcp/pmc/Metric.h>

       CC ... -lpcp_pmc -lpcp

DESCRIPTION

       A QmcMetric object is a container for a single metric and all its values.

       The QmcMetricValue structure is used to hold the instance index, values and errors of each
       instance.  In the case of a singular metric, a single QmcMetricValue object is used.

       A QmcMetric  object  consists  of  a  list  of  QmcMetricValue  objects,  indexes  to  the
       descriptors in the metric's QmcGroup and QmcContext and flags to indicate if the instances
       are  explicit  or  implicit,   and   if   only   active   metrics   are   required   after
       QmcMetric::updateIndom is called.

CONSTRUCTORS

       Metrics  should be constructed through the QmcGroup::addMetric methods as this will ensure
       that the references to the metric's context, descriptor and instance domain are  correctly
       initialized.

INSTANCES

       For  metrics  with  an  instance domain it is possible to add and remove any instance, and
       also update the instance list to reflect changes in a dynamic instance domain.

       bool updateIndom();
           Update  the  metric  to  include  new  instances.   This  method   will   first   call
           QmcContext::update  to  update  the instance domain.  If the active flag is set in the
           QmcGroup::addMetric call, only instances will exported by the  metric,  otherwise  the
           metric will export all instances listed in the domain.

           The ordering of instances may change as a result of this call.  Instances that already
           existed will keep their current and previous values and errors, even if they are in  a
           different order.

       int addInst(QString const& name);
           Add  the  instance name to the metric.  If the instance does not exist in the instance
           domain, a PMAPI(3) error will be returned.  This  method  ignores  the  value  of  the
           active flag set in the QmcMetric constructor.

       void removeInst(uint_t index);
           Remove the instance at position index from the metric.

DIAGNOSTICS

       Error   messages  are  generated  using  pmprintf(3)  but  are  not  flushed.  It  is  the
       responsibility of the user to call pmflush(3) to output any messages.

       Additional diagnostics may be activated by adding the option pmc to the  global  debugging
       specification, as described in pmSetDebug(3).

SEE ALSO

       PMAPI(3), QMC(3), QMC_Context(3), QMC_Group(3), pmflush(3) and pmprintf(3).