# pmreconnectcontext

## 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 re‐
           quests, **pmReconnectContext** will only attempt a reconnection  after
           a  suitable delay from the previous unsuccessful attempt to recon‐
           nect 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 re‐
           define 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 recon‐
           nected source.  The support of dynamic definition for derived met‐
           rics 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, **pmRecon‐**
           **nectContext** does not change the current Performance Metrics Appli‐
           cation 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.  **pmRe‐**
           **connectContext** 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  num‐
           ber  of  seconds  for the desired timeout.  This is most useful in
           cases where the remote host is at the end of a slow  network,  re‐
           quiring longer latencies to establish the connection correctly.
    


## CAVEAT



           Applications that use gethostbyname(3) should exercise caution be‐
           cause  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.
    


## DIAGNOSTICS



           **PM_ERR_NOCONTEXT**
    
                  _handle_ does not identify a valid PMAPI context
    
           **-ETIMEDOUT**
    
                  The re-try time has not elapsed, or the reconnection is at‐
                  tempted and fails.
    


## ENVIRONMENT



           **PMCD_CONNECT_TIMEOUT**
                  Timeout period (in seconds) for pmcd(1) connection at‐
                  tempts.
    
           **PMCD_RECONNECT_TIMEOUT**
                  Redefines the back-off intervals - refer to PMAPI(3).
    


* * *