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 connec
tion 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 accessi
ble.
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 poten
tially block for a long time until the remote machine fin
ishes its initialization. pmReconnectContext will abort
lished 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 reconnec
tion 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 particu
lar, pmNewContext(3) and pmReconnectContext(3) both may
call gethostbyname(3) internally.
Man(1) output converted with
man2html