sig_persistence.h

sig_persistence_key_fn

typedef sig_status_t (*sig_persistence_key_fn)(const char *key, void *ctx);

Called once per key by `list`. `key` is valid only for the duration of the callback; copy it to keep it. A status other than SIG_OK stops the listing and is returned from it.

sig_persistence_module

typedef struct {
    const char *name;
    sig_status_t (*create)(const char *config, void **out_state);
    void (*destroy)(void *state);
    sig_status_t (*load)(void *state, const char *ns, const char *key, void **out_data, size_t *out_len);
    sig_status_t (*save)(void *state, const char *ns, const char *key, const void *data, size_t len);
    sig_status_t (*remove)(void *state, const char *ns, const char *key);
    sig_status_t (*list)(void *state, const char *ns, sig_persistence_key_fn fn, void *ctx);
} sig_persistence_module;

A persistence module (backend) stores opaque blobs under a (namespace, key) pair. What a namespace means is up to the backend (the file backend maps it to a directory), and so is which names it accepts: a backend returns SIG_ERR_INVALID_ARG for a namespace or key it cannot store. `name` and `create` are required. A NULL data hook makes the matching sig_persistence_* call return SIG_ERR_INVALID_ARG. Hooks block; they are meant for configuration I/O, not the event loop's hot path. - load: *out_data is allocated with sig_alloc and owned by the caller. A missing key (or namespace) is SIG_ERR_NOT_FOUND. - save: creates or replaces the key; data is borrowed. - remove: a missing key (or namespace) is SIG_ERR_NOT_FOUND. - list: calls fn once per key stored in ns; a namespace that holds nothing (or does not exist) lists zero keys. The order is backend-defined (the file backend sorts). fn must not save or remove keys in the namespace being listed.

sig_persistence_registry

typedef struct sig_persistence_registry sig_persistence_registry;

sig_persistence_registry_create

sig_status_t sig_persistence_registry_create(sig_persistence_registry ** out)

sig_persistence_registry_destroy

void sig_persistence_registry_destroy(sig_persistence_registry * reg)

sig_persistence_registry_register

sig_status_t sig_persistence_registry_register(sig_persistence_registry * reg, const sig_persistence_module * module)

sig_persistence_registry_lookup

sig_status_t sig_persistence_registry_lookup(const sig_persistence_registry * reg, const char * name, const sig_persistence_module ** out)

sig_persistence

typedef struct {
    const sig_persistence_module *module; /* borrowed */
    void *state;                          /* owned, from module->create */
} sig_persistence;

sig_persistence_create

sig_status_t sig_persistence_create(sig_persistence ** out, const sig_persistence_module * module, const char * config)

sig_persistence_destroy

void sig_persistence_destroy(sig_persistence * p)

sig_persistence_load

sig_status_t sig_persistence_load(sig_persistence * p, const char * ns, const char * key, void ** out_data, size_t * out_len)

out_data is heap-allocated via sig_alloc; caller takes ownership and must sig_free() it. A missing key is SIG_ERR_NOT_FOUND.

sig_persistence_save

sig_status_t sig_persistence_save(sig_persistence * p, const char * ns, const char * key, const void * data, size_t len)

data is borrowed -- the implementation copies what it needs to persist; caller retains ownership and may free/reuse data immediately after this call returns. data may be NULL only when len is 0.

sig_persistence_remove

sig_status_t sig_persistence_remove(sig_persistence * p, const char * ns, const char * key)

A missing key is SIG_ERR_NOT_FOUND.

sig_persistence_list

sig_status_t sig_persistence_list(sig_persistence * p, const char * ns, sig_persistence_key_fn fn, void * ctx)

Calls fn(key, ctx) for each key in ns. A non-SIG_OK status from fn stops the listing and is returned.