sapi_clocksync.h File Reference

Pluggable wall-clock synchronization backend (ADR-017). More...

#include <stdint.h>
#include "safeapi/utils/status/sapi_status.h"
#include "safeapi/utils/types/sapi_types.h"

Include dependency graph for sapi_clocksync.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations
enum	sapi_clocksync_quality_t { SAPI_CLOCKSYNC_UNSYNCHRONIZED = 0 , SAPI_CLOCKSYNC_DEGRADED = 1 , SAPI_CLOCKSYNC_SYNCHRONIZED = 2 }
	Coarse quality/confidence of the current clock synchronization. More...

Functions
sapi_status_t	sapi_clocksync_get_offset_ms (int64_t *out_offset_ms)
	Reports this node's estimated clock offset (diagnostic/timeout- sizing only - see the file-level note; never use this to decide whether channel results are comparable).
sapi_status_t	sapi_clocksync_get_quality (sapi_clocksync_quality_t *out_quality)
	Reports the backend's current confidence in the clock offset.

Detailed Description

Pluggable wall-clock synchronization backend (ADR-017).

Exposes a per-node clock offset/quality query, backed by whatever real synchronization mechanism an integrator plugs in (PTP, GPS discipline, NTP, or a custom link) - no protocol implementation is bundled here, only the pluggable interface, following the same sapi_<service>_backend_t + sapi_<service>_register_backend() pattern sapi_timer already uses (ADR-005).

IMPORTANT - what this module is not for: it does not decide whether two vital channels are synchronized for comparison purposes. That correctness argument comes entirely from sapi_checkpoint.h's bounded checkpoint-ID rendezvous (ADR-017 section 2.2), which works correctly even with zero clock synchronization. sapi_clocksync exists for two narrower purposes only:

1. Diagnostics - correlating log/event timestamps across geographically separate nodes that otherwise have no common time reference.
2. Sizing sapi_checkpoint_config_t::max_delay_ms for a given deployment's actual known clock/network jitter, instead of guessing.

A caller that reads a low reported offset and concludes "therefore the channels' results are simultaneous" is misusing this module - that conclusion is never valid on its own; only a confirmed matching checkpoint ID within sapi_checkpoint's timeout is.

Definition in file sapi_clocksync.h.