18.2.24. PMIx_Heartbeat

PMIx_Heartbeat — Send a heartbeat to the local PMIx server.

18.2.24.1. SYNOPSIS

#include <pmix.h>

void PMIx_Heartbeat(void);

18.2.24.2. DESCRIPTION

Send a single heartbeat to the local PMIx server. PMIx_Heartbeat is a convenience wrapper around PMIx_Process_monitor(3) (equivalent to passing the PMIX_SEND_HEARTBEAT attribute as the monitor action): it transmits a lightweight, one-way message to the server and returns immediately.

Heartbeats feed the server-side liveness monitoring that is configured through PMIx_Process_monitor(3) with the PMIX_MONITOR_HEARTBEAT action. A process that has registered to be watched for heartbeats is expected to call PMIx_Heartbeat often enough to satisfy the window established by the PMIX_MONITOR_HEARTBEAT_TIME and PMIX_MONITOR_HEARTBEAT_DROPS directives. If the server does not receive the expected heartbeats within that window, it generates the monitoring event (e.g., PMIX_MONITOR_HEARTBEAT_ALERT) that the requestor set up.

PMIx_Heartbeat takes no arguments. If the library’s progress engine has been stopped, or the message cannot be built or sent, the call silently returns without emitting a heartbeat.

18.2.24.3. RETURN VALUE

PMIx_Heartbeat returns no value (void). Any failure to send the heartbeat — for example, because the progress engine has been stopped — is not reported to the caller.

18.2.24.4. NOTES

Because the heartbeat is delivered as a best-effort, one-way message and the function returns no status, callers cannot detect a failed transmission from the call itself. Detection of a missing heartbeat is instead surfaced through the monitoring event registered via PMIx_Process_monitor(3).

Sending heartbeats is only meaningful for a process (client or tool) connected to a local server; a server does not send heartbeats to itself.