1PMRECONNECTCONTEXT(3) Library Functions Manual PMRECONNECTCONTEXT(3)
2
6 pmReconnectContext - reconnect to a PMAPI context
7
9 #include <pcp/pmapi.h>
10 int pmReconnectContext(int handle);
12 cc ... -lpcp
14
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
18 established and then subsequently lost.
19 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 When the source of metrics associated with the context handle is
25 pmcd(1), then to avoid flooding the system with reconnect requests,
26 pmReconnectContext will only attempt a reconnection after a suitable
27 delay 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 The environment variable PMCD_RECONNECT_TIMEOUT may be used to redefine
34 the back-off intervals, see PMAPI(3).
35 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 If handle identifies a context associated with an archive source of
41 metrics, pmReconnectContext returns without delay.
42 If the reconnection succeeds, pmReconnectContext returns handle.
44 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
49 dynamic definition for derived metrics provides one use case where
50 pmReconnectContext may be called even if the connection to the metrics
51 source has not been lost.
52 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 When attempting to connect to a remote pmcd(1) on a machine that is
58 booting, pmReconnectContext could potentially block for a long time
59 until the remote machine finishes its initialization. pmReconnectCon‐
60 text will abort and return an error if the connection has not been
61 established after some specified interval has elapsed. The default
62 interval is 5 seconds. This may be modified by setting PMCD_CON‐
63 NECT_TIMEOUT in the environment to a real number of seconds for the
64 desired timeout. This is most useful in cases where the remote host is
65 at the end of a slow network, requiring longer latencies to establish
66 the connection correctly.
67
69 PMCD_CONNECT_TIMEOUT
70 Timeout period (in seconds) for pmcd(1) connection attempts.
71 PMCD_RECONNECT_TIMEOUT
73 Redefines the back-off intervals - refer to PMAPI(3).
74
76 pmcd(1), PMAPI(3), pmLoadDerivedConfig(3), pmNewContext(3), pmRegister‐
77 Derived(3), pmRegisterDerivedMetric(3) and pmUseContext(3).
78
80 PM_ERR_NOCONTEXT
81 handle does not identify a valid PMAPI context
83 -ETIMEDOUT
85 The re-try time has not elapsed, or the reconnection is
87 attempted and fails.
88
90 Applications that use gethostbyname(3) should exercise caution because
91 the static fields in struct hostent may not be preserved across some
92 PMAPI(3) calls. In particular, pmNewContext(3) and pmReconnectCon‐
93 text(3) both may call gethostbyname(3) internally.
94Performance Co-Pilot PCP PMRECONNECTCONTEXT(3)