pmreconnectcontext(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | CAVEAT | DIAGNOSTICS | ENVIRONMENT | SEE ALSO | COLOPHON

PMRECONNECTCONTEXT(3)    Library Functions Manual   PMRECONNECTCONTEXT(3)

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 re‐
       quests, pmReconnectContext will only attempt a reconnection  after
       a  suitable delay from the previous unsuccessful attempt to recon‐
       nect 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 re‐
       define 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 recon‐
       nected source.  The support of dynamic definition for derived met‐
       rics 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, pmRecon‐
       nectContext does not change the current Performance Metrics Appli‐
       cation 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.  pmRe‐
       connectContext 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  num‐
       ber  of  seconds  for the desired timeout.  This is most useful in
       cases where the remote host is at the end of a slow  network,  re‐
       quiring longer latencies to establish the connection correctly.

CAVEAT         top

       Applications that use gethostbyname(3) should exercise caution be‐
       cause  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

       PM_ERR_NOCONTEXT

              handle does not identify a valid PMAPI context

       -ETIMEDOUT

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

ENVIRONMENT         top

       PMCD_CONNECT_TIMEOUT
              Timeout period (in seconds) for pmcd(1) connection at‐
              tempts.

       PMCD_RECONNECT_TIMEOUT
              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
       pmUseContext(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2025-08-11.  (At that time, the date of the most recent commit
       that was found in the repository was 2025-08-11.)  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 man-pages@man7.org

Performance Co-Pilot               PCP              PMRECONNECTCONTEXT(3)

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