Man Linux: Main Page and Category List

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 applications 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 PMCD is accessible.

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

       If the reconnection succeeds, pmReconnectContext returns handle.

       If handle identifies a context associated with  an  archive  source  of
       metrics, pmReconnectContext does nothing and returns handle.

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

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

       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), pmNewContext(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(4)     calls.      In     particular,     pmNewContext(3)     and
       pmReconnectContext(3) both may call gethostbyname(3) internally.