pmreconnectcontext(3) — Linux manual page



NAME         top

       pmReconnectContext - reconnect to a PMAPI context

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       int pmReconnectContext(int handle);

       cc ... -lpcp

DESCRIPTION         top

       As a consequence of network, host or Performance Metrics
       Collector Daemon (PMCD) failures, an application's connection 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 metrics source is accessible.

       When the source of metrics associated with the context handle is
       pmcd(1), then 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).

       Calling pmReconnectContext with a handle identifying a currently
       connected pmcd(1) context will cause the connection to be broken
       before any reconnection is attempted.

       If handle identifies a context associated with an archive source
       of metrics, pmReconnectContext returns without delay.

       If the reconnection succeeds, pmReconnectContext returns handle.

       As a side-effect of reconnecting, any derived metrics that have
       previously been defined using pmRegisterDerived(3),
       pmRegisterDerivedMetric(3) or pmLoadDerivedConfig(3) will be re-
       processed and re-bound to the available metrics from the
       reconnected source.  The support of dynamic definition for
       derived metrics provides one use case where pmReconnectContext
       may be called even if the connection to the metrics source has
       not been lost.

       Note that even in the case of a successful reconnection,
       pmReconnectContext does not change the current Performance
       Metrics Application Programming Interface (PMAPI) context, so
       handle remains valid.

       When attempting to connect to a remote pmcd(1) on a machine that
       is booting, pmReconnectContext could potentially block for a long
       time until the remote machine finishes its initialization.
       pmReconnectContext will abort and return an error if the
       connection has not been established 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

CAVEAT         top

       Applications that use gethostbyname(3) should exercise caution
       because the static fields in struct hostent may not be preserved
       across some PMAPI(3) calls.  In particular, pmNewContext(3) and
       pmReconnectContext(3) both may call gethostbyname(3) internally.

DIAGNOSTICS         top


              handle does not identify a valid PMAPI context


              The re-try time has not elapsed, or the reconnection is
              attempted and fails.

ENVIRONMENT         top

              Timeout period (in seconds) for pmcd(1) connection

              Redefines the back-off intervals - refer to PMAPI(3).

SEE ALSO         top

       pmcd(1), PMAPI(3), pmLoadDerivedConfig(3), pmNewContext(3),
       pmRegisterDerived(3), pmRegisterDerivedMetric(3) and

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at 
       ⟨⟩.  If you have a bug report for this manual
       page, send it to  This page was obtained from the
       project's upstream Git repository
       ⟨⟩ on 2023-12-22.
       (At that time, the date of the most recent commit that was found
       in the repository was 2023-12-16.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to

Performance Co-Pilot               PCP             PMRECONNECTCONTEXT(3)

Pages that refer to this page: pmnewcontext(3)pmreconnectcontext(3)pmregisterderived(3)