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.