NAME

       pmReconnectContext - reconnect to a PMAPI context

C SYNOPSIS

       #include <pcp/pmapi.h>

       int pmReconnectContext(int handle);

       cc ... -lpcp

DESCRIPTION

       As a consequence of network, host or Performance Metrics Collector Daemon (PMCD) failures,
       an application's connection to a PMCD may be established and then subsequently lost.

       The  routine  pmReconnectContext  allows  an  application  to  request  that  the  context
       identified  by  handle should be re-established, provided the associated metrics source is
       accessible.

       When the source of metrics associated with the context handle is pmcd(1),  then  to  avoid
       flooding  the  system  with  reconnect  requests,  pmReconnectContext  will only attempt a
       reconnection after a suitable delay from the previous unsuccessful  attempt  to  reconnect
       this  context.  This  imposed  restriction  on  the reconnect re-try time interval uses an
       exponential back-off so that the initial delay is 5 seconds after the  first  unsuccessful
       attempt, then 10 seconds, then 20 seconds, then 40 seconds and then 80 seconds thereafter.

       The  environment  variable  PMCD_RECONNECT_TIMEOUT  may  be  used to redefine the back-off
       intervals, see PMAPI(3).

       Calling pmReconnectContext with a handle identifying a currently connected pmcd(1) context
       will cause the connection to be broken before any reconnection is attempted.

       If   handle   identifies   a  context  associated  with  an  archive  source  of  metrics,
       pmReconnectContext returns without delay.

       If the reconnection succeeds, pmReconnectContext returns handle.

       As a side-effect of reconnecting, any derived metrics that have  previously  been  defined
       using  pmRegisterDerived(3),  pmRegisterDerivedMetric(3) or pmLoadDerivedConfig(3) will be
       re-processed and re-bound to the available  metrics  from  the  reconnected  source.   The
       support   of   dynamic  definition  for  derived  metrics  provides  one  use  case  where
       pmReconnectContext may be called even if the connection to the metrics source has not been
       lost.

       Note  that  even  in  the  case  of a successful reconnection, pmReconnectContext does not
       change the current Performance Metrics Application Programming Interface (PMAPI)  context,
       so handle remains valid.

       When   attempting  to  connect  to  a  remote  pmcd(1)  on  a  machine  that  is  booting,
       pmReconnectContext could potentially block for  a  long  time  until  the  remote  machine
       finishes  its  initialization.   pmReconnectContext  will abort and return an error if the
       connection has not been established  after  some  specified  interval  has  elapsed.   The
       default  interval  is  5 seconds.  This may be modified by setting PMCD_CONNECT_TIMEOUT in
       the environment to a real number of seconds for the desired timeout.  This is most  useful
       in cases where the remote host is at the end of a slow network, requiring longer latencies
       to establish the connection correctly.

ENVIRONMENT

       PMCD_CONNECT_TIMEOUT
              Timeout period (in seconds) for pmcd(1) connection attempts.

       PMCD_RECONNECT_TIMEOUT
              Redefines the back-off intervals - refer to PMAPI(3).

SEE ALSO

       pmcd(1),   PMAPI(3),   pmLoadDerivedConfig(3),   pmNewContext(3),    pmRegisterDerived(3),
       pmRegisterDerivedMetric(3) and pmUseContext(3).

DIAGNOSTICS

       PM_ERR_NOCONTEXT

              handle does not identify a valid PMAPI context

       -ETIMEDOUT

              The re-try time has not elapsed, or the reconnection is attempted and fails.

CAVEAT

       Applications  that  use gethostbyname(3) should exercise caution because the static fields
       in struct hostent may not  be  preserved  across  some  PMAPI(3)  calls.   In  particular,
       pmNewContext(3) and pmReconnectContext(3) both may call gethostbyname(3) internally.