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 es‐
18 tablished 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, 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 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 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 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 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
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
75 PM_ERR_NOCONTEXT
76 handle does not identify a valid PMAPI context
78 -ETIMEDOUT
80 The re-try time has not elapsed, or the reconnection is at‐
82 tempted and fails.
83
85 PMCD_CONNECT_TIMEOUT
86 Timeout period (in seconds) for pmcd(1) connection attempts.
87 PMCD_RECONNECT_TIMEOUT
89 Redefines the back-off intervals - refer to PMAPI(3).
90
92 pmcd(1), PMAPI(3), pmLoadDerivedConfig(3), pmNewContext(3), pmRegister‐
93 Derived(3), pmRegisterDerivedMetric(3) and pmUseContext(3).
94Performance Co-Pilot PCP PMRECONNECTCONTEXT(3)