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 applications connection to a PMCD may be estab‐
18       lished 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 PMCD is accessible.
23
24       To  avoid  flooding the system with reconnect requests, pmReconnectCon‐
25       text will only attempt a reconnection after a suitable delay  from  the
26       previous  unsuccessful  attempt to reconnect this context. This imposed
27       restriction on the reconnect re-try time interval uses  an  exponential
28       back-off  so that the initial delay is 5 seconds after the first unsuc‐
29       cessful attempt, then 10 seconds, then 20 seconds, then 40 seconds  and
30       then 80 seconds thereafter.
31
32       The environment variable PMCD_RECONNECT_TIMEOUT may be used to redefine
33       the back-off intervals, see PMAPI(3).
34
35       If the reconnection succeeds, pmReconnectContext returns handle.
36
37       If handle identifies a context associated with  an  archive  source  of
38       metrics, pmReconnectContext does nothing and returns handle.
39
40       Calling  pmReconnectContext  with a handle identifying a currently con‐
41       nected context will cause the connection to be broken before any recon‐
42       nection is attempted.
43
44       Note  that  even in the case of a successful reconnection, pmReconnect‐
45       Context does not change the  current  Performance  Metrics  Application
46       Programming Interface (PMAPI) context.
47
48       When  attempting  to  connect  to a remote pmcd(1) on a machine that is
49       booting, pmReconnectContext could potentially block  for  a  long  time
50       until  the remote machine finishes its initialization.  pmReconnectCon‐
51       text will abort and return an error if  the  connection  has  not  been
52       established  after  some  specified  interval has elapsed.  The default
53       interval is 5 seconds.  This  may  be  modified  by  setting  PMCD_CON‐
54       NECT_TIMEOUT  in  the  environment  to a real number of seconds for the
55       desired timeout.  This is most useful in cases where the remote host is
56       at  the  end of a slow network, requiring longer latencies to establish
57       the connection correctly.
58

ENVIRONMENT

60       PMCD_CONNECT_TIMEOUT
61              Timeout period (in seconds) for pmcd(1) connection attempts.
62
63       PMCD_RECONNECT_TIMEOUT
64              Redefines the back-off intervals - refer to PMAPI(3).
65

SEE ALSO

67       pmcd(1), PMAPI(3), pmNewContext(3) and pmUseContext(3).
68

DIAGNOSTICS

70       PM_ERR_NOCONTEXT
71
72              handle does not identify a valid PMAPI context
73
74       -ETIMEDOUT
75
76              The  re-try  time  has  not  elapsed,  or  the  reconnection  is
77              attempted and fails.
78

CAVEAT

80       Applications  that use gethostbyname(3) should exercise caution because
81       the static fields in struct hostent may not be  preserved  across  some
82       PMAPI(3)  calls.   In  particular,  pmNewContext(3) and pmReconnectCon‐
83       text(3) both may call gethostbyname(3) internally.
84
85
86
87Performance Co-Pilot                  PCP                PMRECONNECTCONTEXT(3)