- Generated by
1.18.0
|
Safe API Framework
Layered API framework for safety-related applications (ERTMS RBC reference targeting CENELEC EN 50128 SIL 4)
|
Application lifecycle operations. More...
#include <sapi_appmanager.h>
Data Fields | |
| sapi_status_t(*) | init (void *context) |
| Initialize application. | |
| sapi_status_t(*) | pre_execute (void *context) |
| Optional per-cycle input/prepare stage (ADR-019). | |
| sapi_status_t(*) | execute (void *context) |
| Execute main application logic. | |
| sapi_status_t(*) | post_execute (void *context) |
| Optional per-cycle output/cleanup stage (ADR-019). | |
| sapi_status_t(*) | on_checkpoint_result (void *context, bool committed) |
| Optional per-cycle checkpoint outcome hook (ADR-034). | |
| sapi_status_t(*) | shutdown (void *context) |
| Shutdown application. | |
| const char *(*) | get_name (void) |
| Get human-readable application name. | |
| const char *(*) | get_version (void) |
| Get application version string. | |
Application lifecycle operations.
Each application must implement these operations to be managed by the application manager.
REQ-APPMANAGER-002: Applications shall implement all mandatory operations in the sapi_appmanager_operations_t interface (init, execute, shutdown, get_name, get_version). pre_execute and post_execute are optional (ADR-019, REQ-APPMANAGER-006) and may be left NULL.
Definition at line 116 of file sapi_appmanager.h.
| sapi_status_t(*) sapi_appmanager_operations_t::init(void *context) |
Initialize application.
Called once at startup. Should initialize all services, resources, and state. If initialization fails, the application is not started.
| context | Application-specific context pointer |
Definition at line 126 of file sapi_appmanager.h.
| sapi_status_t(*) sapi_appmanager_operations_t::pre_execute(void *context) |
Optional per-cycle input/prepare stage (ADR-019).
If non-NULL, called once per iteration immediately before execute() (and, if configured, immediately after that cycle's checkpoint rendezvous - see sapi_appmanager_config_t::checkpoint). Intended for "read/prepare this cycle's inputs" work that a dual-channel application wants to keep separate from its decision logic. May be NULL, in which case this stage is skipped - existing applications that only implement execute() are unaffected.
A non-OK return is handled exactly like execute() returning non-OK: logged, counted against error_count, and checked against error_threshold; execute() and post_execute() are still skipped for that iteration in that case (see sapi_appmanager_run()).
| context | Application-specific context pointer |
Definition at line 148 of file sapi_appmanager.h.
| sapi_status_t(*) sapi_appmanager_operations_t::execute(void *context) |
Execute main application logic.
Called in a loop after initialization. The execute function should process one iteration of work and return. Returning non-OK status may trigger shutdown depending on error severity.
| context | Application-specific context pointer |
Definition at line 161 of file sapi_appmanager.h.
| sapi_status_t(*) sapi_appmanager_operations_t::post_execute(void *context) |
Optional per-cycle output/cleanup stage (ADR-019).
If non-NULL, called once per iteration immediately after execute() returns SAPI_STATUS_OK. Intended for "send this cycle's outputs" work that a dual-channel application wants to keep separate from its decision logic. May be NULL, in which case this stage is skipped - existing applications that only implement execute() are unaffected.
A non-OK return is handled exactly like execute() returning non-OK: logged, counted against error_count, and checked against error_threshold.
| context | Application-specific context pointer |
Definition at line 181 of file sapi_appmanager.h.
| sapi_status_t(*) sapi_appmanager_operations_t::on_checkpoint_result(void *context, bool committed) |
Optional per-cycle checkpoint outcome hook (ADR-034).
If non-NULL and config->checkpoint is configured, called exactly once per cycle immediately after the checkpoint stage (the last stage of the cycle - see this header's own file-level doc and sapi_appmanager_run()'s doc for the stage order). Intended for a "stage output during the cycle, only actually transmit it here" pattern: committed is true when this cycle's checkpoint signature matched the peer's (or checkpoint is disabled/paused - see below), meaning any output staged during pre_execute()/execute()/ post_execute() may now be safely sent; false only when sapi_channel_checkpoint() itself returned non-OK (a genuine validation failure or timeout - REQ-CHECKPOINT-003 has already driven this process to SAPI_SAFESTATE_LEVEL_SAFE by the time this is called), meaning staged output for this cycle should be discarded, never transmitted.
Called with committed=true (never false) when config->checkpoint is NULL, or when config->checkpoint->voter is NULL (checkpointing paused) - an application using the stage-then-commit pattern does not need to special-case "was checkpoint even active this cycle"; disabled/paused checkpointing simply never withholds a commit. May be NULL, in which case this hook is skipped entirely - existing applications that do not stage output are unaffected.
A non-OK return is handled exactly like the other optional stages: logged and counted against error_count/error_threshold.
| context | Application-specific context pointer |
| committed | true if this cycle's output may be sent; false if it must be discarded |
Definition at line 219 of file sapi_appmanager.h.
| sapi_status_t(*) sapi_appmanager_operations_t::shutdown(void *context) |
Shutdown application.
Called once at shutdown. Should release resources and perform graceful cleanup. This is always called, even if init/execute failed.
| context | Application-specific context pointer |
Note: This function must not fail. It should handle all cleanup robustly, logging errors but continuing cleanup.
Definition at line 233 of file sapi_appmanager.h.
| const char *(*) sapi_appmanager_operations_t::get_name(void) |
Get human-readable application name.
Used for logging and diagnostics.
Definition at line 242 of file sapi_appmanager.h.
| const char *(*) sapi_appmanager_operations_t::get_version(void) |
Get application version string.
Used for logging and version tracking.
Definition at line 251 of file sapi_appmanager.h.
1.18.0