Optional built-in checkpoint rendezvous configuration (ADR-019/ADR-034). More...

#include <sapi_appmanager.h>

Collaboration diagram for sapi_appmanager_checkpoint_config_t:

Data Fields
sapi_voter_t *	voter
sapi_duration_ms_t	max_delay_ms
uint32_t	expected_node_count
sapi_watchdog_t	watchdog

Detailed Description

Optional built-in checkpoint rendezvous configuration (ADR-019/ADR-034).

When attached to sapi_appmanager_config_t::checkpoint, sapi_appmanager_run() calls sapi_channel_checkpoint() once at the END of every cycle - after pre_execute()/execute()/post_execute() have all run - using this cycle's own folded checkpoint-mark signature (see this header's file-level ADR-034 doc and SAPI_CHECKPOINT_MARK()) as the checkpoint's checkpoint_id.

ADR-034 history: this used to run FIRST, before pre_execute(), using the running sapi_appmanager_state_t::iteration_count as checkpoint_id, on the theory that "no separate per-cycle counter is needed." That broke in practice: iteration_count is a process-local counter that resets to 0 on every reboot, and two independently-rebooting channels' counters have no reason to ever coincide again after either one reboots alone - REQ- CHECKPOINT-002 would then correctly (but uselessly) keep rejecting every reply as "wrong checkpoint_id" until, by chance, both channels next rebooted together. The mark-signature scheme replaces the counter with a value that is naturally equal on both sides whenever they actually took the same program path this cycle, regardless of either side's reboot history.

Leave sapi_appmanager_config_t::checkpoint NULL to disable this entirely (the default); this is opt-in because sapi_channel_checkpoint() blocks for up to max_delay_ms, which is only wanted by applications that are actually part of a synchronized multi-channel group.

Safety:: A checkpoint timeout does not introduce a second safety reaction: sapi_channel_checkpoint() has already called sapi_safestate_enter() at SAPI_SAFESTATE_LEVEL_SAFE (REQ-CHECKPOINT-003) before returning SAPI_STATUS_TIMEOUT to sapi_appmanager_run(), which then folds that status into its ordinary error_count/error_threshold handling like any other failed stage (REQ-APPMANAGER-007). Note that with this framework's shipped sapi_safestate.c, entering SAPI_SAFESTATE_LEVEL_SAFE is an unconditional, permanent halt (REQ-COMMON-SAFESTATE-002), so this error_count path is a defensive fallback - correct if ever reached - rather than the expected outcome of a real timeout.

Definition at line 293 of file sapi_appmanager.h.

Field Documentation

◆ voter

sapi_voter_t* sapi_appmanager_checkpoint_config_t::voter

Checkpoint target: a voter with its channels already registered (ADR-025 - previously a single sapi_channel_t; that type is now one link, registered N-per-voter). May still be NULL when sapi_appmanager_run() is first called, e.g. if an integrator's own init() is what populates it. May also be set back to NULL at runtime (e.g. from a background reconnect task) to pause checkpointing without that being treated as an error - see sapi_appmanager_run()'s own doc.

Definition at line 294 of file sapi_appmanager.h.

◆ max_delay_ms

sapi_duration_ms_t sapi_appmanager_checkpoint_config_t::max_delay_ms

Forwarded to sapi_checkpoint_config_t::max_delay_ms.

Definition at line 302 of file sapi_appmanager.h.

◆ expected_node_count

uint32_t sapi_appmanager_checkpoint_config_t::expected_node_count

Forwarded to sapi_checkpoint_config_t::expected_node_count.

Definition at line 303 of file sapi_appmanager.h.

◆ watchdog

sapi_watchdog_t sapi_appmanager_checkpoint_config_t::watchdog

Optional liveness watchdog kicked on success; may be NULL.

Definition at line 304 of file sapi_appmanager.h.

The documentation for this struct was generated from the following file:

include/safeapi/app/appmanager/sapi_appmanager.h