PMRECONNECTCONTEXT(3)

💖 PMRECONNECTCONTEXT 💖

okay bestie, so you know how this whole page is PMRECONNECTCONTEXT(3) from the Library Functions Manual? yeah. it's the reconnect-to-your-PMAPI-context era and honestly? iconic. let's get into it 🫶

---

✨ NAME ✨

pmReconnectContext — reconnect to a PMAPI context 🔌

---

🌸 C SYNOPSIS 🌸

#include <pcp/pmapi.h>

int pmReconnectContext(int handle);

cc ... -lpcp

---

🦋 DESCRIPTION 🦋

so picture this: the network ghosts you. the host ghosts you. or the Performance Metrics Collector Daemon (PMCD) itself ghosts you. and suddenly your app's connection to a PMCD, which was literally fine a second ago, is gone. it's giving situationship, ngl. 😭

pmReconnectContext is your bestie that lets you say "hey, please re-establish the context identified by handle" — as long as the metrics source it's attached to is actually reachable. no cap.

now here's the tea 🍵: when the source of metrics for that handle is pmcd(1), we do NOT want you spamming reconnect requests into the void and flooding the whole system. so pmReconnectContext only tries again after a suitable delay since the last failed attempt. and because one delay isn't dramatic enough, it uses an exponential back-off:

• initial delay is 5 seconds after the first unsuccessful attempt
• then 10 seconds
• then 20 seconds
• then 40 seconds
• then 80 seconds thereafter

the way it just doubles 💅 obsessed.

the environment variable PMCD_RECONNECT_TIMEOUT can redefine those back-off intervals — go peek at PMAPI(3) for the deets.

calling pmReconnectContext with a handle that identifies a currently connected pmcd(1) context? it will break that connection before any reconnection is even attempted. bye babe, we're rebuilding. 🔨

if handle identifies a context tied to an archive source of metrics, pmReconnectContext returns without delay. no waiting around, she's ready.

if the reconnection succeeds, pmReconnectContext returns handle. slay. ✅

now for the side-effect that nobody expects but everyone needs: any derived metrics you previously defined with pmRegisterDerived(3), pmRegisterDerivedMetric(3), or pmLoadDerivedConfig(3) get re-processed and re-bound to the metrics available from the reconnected source. and honestly? that dynamic-definition support is one use case where you might call pmReconnectContext even if your connection to the metrics source was never lost in the first place. main character behavior fr fr. ✨

heads up bestie: even on a successful reconnection, pmReconnectContext does not change the current Performance Metrics Application Programming Interface (PMAPI) context. so handle stays valid. no switching up on you. 🫶

one more thing 😭: if you're trying to connect to a remote pmcd(1) on a machine that's currently booting, pmReconnectContext could lowkey block for a long time until that remote machine finishes its initialization. it will abort and return an error if the connection still isn't established after some specified interval has elapsed. the default interval is 5 seconds. you can modify this by setting PMCD_CONNECT_TIMEOUT in the environment to a real number of seconds for whatever timeout you want. this is highkey most useful when the remote host is at the end of a slow network and needs longer latencies to establish the connection correctly. 🌐

---

⚠️ CAVEAT ⚠️

apps that use gethostbyname(3) need to be careful, okay? because the static fields in struct hostent may not be preserved across some PMAPI(3) calls. specifically — and this is the important part — both pmNewContext(3) and pmReconnectContext(3) may call gethostbyname(3) internally. so don't be out here holding onto those fields like they're forever. 💀

---

🎀 DIAGNOSTICS 🎀

• PM_ERR_NOCONTEXT — handle does not identify a valid PMAPI context. bestie that handle is not it. 🙈
• -ETIMEDOUT — the re-try time has not elapsed, or the reconnection is attempted and fails. ⏰

---

🌈 ENVIRONMENT 🌈

• PMCD_CONNECT_TIMEOUT — Timeout period (in seconds) for pmcd(1) connection attempts.
• PMCD_RECONNECT_TIMEOUT — Redefines the back-off intervals — refer to PMAPI(3).

---

💜 SEE ALSO 💜

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

---

and that's the whole page, bestie 🥰 brought to you by Performance Co-Pilot — that's PCP for the girlies who abbreviate — and this lil masterpiece is dated and stamped as PMRECONNECTCONTEXT(3). go reconnect something iconic. mwah 💅✨