sig_host.h

sig_host_module

typedef struct {
    const sig_runtime_module *module; /* borrowed; must outlive sig_host_run() */
    const char *config;               /* may be NULL; copied by the runtime */
} sig_host_module;

sig_host_config

typedef struct {
    const sig_persistence_module *store_module; /* required; borrowed, must outlive sig_host_run() */
    const char *store_config;                   /* handed to store_module->create (for the file
                                                 * backend, the base directory); may be NULL if the
                                                 * module accepts that; copied by the module */
    const sig_capsule_registry *capsules;       /* required; borrowed */
    const sig_host_module *modules;             /* registered in order */
    size_t num_modules;                         /* modules may be NULL iff 0 */
    bool single_threaded;                       /* drive services from one sig_loop, not a thread each */
} sig_host_config;

sig_host_platform

typedef struct {
    sig_status_t (*arm_shutdown)(sig_runtime *rt, void **out_state);
    void (*disarm_shutdown)(void *state);
} sig_host_platform;

How a platform makes a shutdown request reach the runtime (e.g. a sigwait thread calling sig_runtime_request_shutdown). Both hooks are nullable. arm_shutdown runs before sig_runtime_start so the trigger is already in place during startup; disarm_shutdown runs after sig_runtime_stop and only if arm_shutdown succeeded, receiving the state arm_shutdown produced. Note sig_runtime_start() clears any request made before it begins.

sig_host_run

sig_status_t sig_host_run(const sig_host_config * cfg, const sig_host_platform * plat)

Runs the whole lifecycle and returns when the runtime has been stopped and destroyed. Returns SIG_OK after a clean shutdown; otherwise the status of the first step that failed (a failure at any step unwinds the earlier steps in reverse order). SIG_ERR_INVALID_ARG for a NULL cfg/capsules, a NULL store_module (or one without a `create` hook), or a NULL `module` in cfg->modules. The store is created before anything is armed; if the module's `create` fails, its status is returned. The host does not inspect store_config: it does not check that a file store's directory exists (the file backend creates it on first save), so a caller that wants a typo'd path to fail must check it first. `plat` may be NULL (no platform trigger: shutdown must then come from a runtime module).