1PMRECONNECTCONTEXT(3)      Library Functions Manual      PMRECONNECTCONTEXT(3)
2
3
4

NAME

6       pmReconnectContext - reconnect to a PMAPI context
7

C SYNOPSIS

9       #include <pcp/pmapi.h>
10
11       int pmReconnectContext(int handle);
12
13       cc ... -lpcp
14

DESCRIPTION

16       As a consequence of network, host or Performance Metrics Collector Dae‐
17       mon (PMCD) failures, an application's connection to a PMCD may  be  es‐
18       tablished and then subsequently lost.
19
20       The  routine  pmReconnectContext  allows an application to request that
21       the context identified by handle should be re-established, provided the
22       associated metrics source is accessible.
23
24       When  the  source  of  metrics  associated  with  the context handle is
25       pmcd(1), then to avoid flooding the system with reconnect requests, pm‐
26       ReconnectContext  will only attempt a reconnection after a suitable de‐
27       lay from the previous unsuccessful attempt to reconnect  this  context.
28       This  imposed restriction on the reconnect re-try time interval uses an
29       exponential back-off so that the initial delay is 5 seconds  after  the
30       first  unsuccessful  attempt, then 10 seconds, then 20 seconds, then 40
31       seconds and then 80 seconds thereafter.
32
33       The environment variable PMCD_RECONNECT_TIMEOUT may be used to redefine
34       the back-off intervals, see PMAPI(3).
35
36       Calling  pmReconnectContext  with a handle identifying a currently con‐
37       nected pmcd(1) context will cause the connection to  be  broken  before
38       any reconnection is attempted.
39
40       If  handle  identifies  a  context associated with an archive source of
41       metrics, pmReconnectContext returns without delay.
42
43       If the reconnection succeeds, pmReconnectContext returns handle.
44
45       As a side-effect of reconnecting, any derived metrics that have  previ‐
46       ously  been  defined  using pmRegisterDerived(3), pmRegisterDerivedMet‐
47       ric(3) or pmLoadDerivedConfig(3) will be re-processed and  re-bound  to
48       the  available metrics from the reconnected source.  The support of dy‐
49       namic definition for derived metrics provides one use case where  pmRe‐
50       connectContext  may  be  called  even  if the connection to the metrics
51       source has not been lost.
52
53       Note that even in the case of a successful  reconnection,  pmReconnect‐
54       Context  does  not  change  the current Performance Metrics Application
55       Programming Interface (PMAPI) context, so handle remains valid.
56
57       When attempting to connect to a remote pmcd(1) on  a  machine  that  is
58       booting, pmReconnectContext could potentially block for a long time un‐
59       til the remote machine finishes its initialization.  pmReconnectContext
60       will  abort  and  return an error if the connection has not been estab‐
61       lished after some specified interval has elapsed.  The default interval
62       is  5 seconds.  This may be modified by setting PMCD_CONNECT_TIMEOUT in
63       the environment to a real number of seconds for  the  desired  timeout.
64       This  is  most useful in cases where the remote host is at the end of a
65       slow network, requiring longer latencies to  establish  the  connection
66       correctly.
67

CAVEAT

69       Applications  that use gethostbyname(3) should exercise caution because
70       the static fields in struct hostent may not be  preserved  across  some
71       PMAPI(3)  calls.   In  particular,  pmNewContext(3) and pmReconnectCon‐
72       text(3) both may call gethostbyname(3) internally.
73

DIAGNOSTICS

75       PM_ERR_NOCONTEXT
76
77              handle does not identify a valid PMAPI context
78
79       -ETIMEDOUT
80
81              The re-try time has not elapsed,  or  the  reconnection  is  at‐
82              tempted and fails.
83

ENVIRONMENT

85       PMCD_CONNECT_TIMEOUT
86              Timeout period (in seconds) for pmcd(1) connection attempts.
87
88       PMCD_RECONNECT_TIMEOUT
89              Redefines the back-off intervals - refer to PMAPI(3).
90

SEE ALSO

92       pmcd(1), PMAPI(3), pmLoadDerivedConfig(3), pmNewContext(3), pmRegister‐
93       Derived(3), pmRegisterDerivedMetric(3) and pmUseContext(3).
94
95
96
97Performance Co-Pilot                  PCP                PMRECONNECTCONTEXT(3)
Impressum