atomic_store.h

#ifndef ATOMIC_STORE_H
#define ATOMIC_STORE_H

#include <stddef.h>


/* Opaque types */
typedef struct aw_store aw_store_t;
typedef struct aw_tx    aw_tx_t;

/* Open a store file.
 *
 * path              : path to the single big store file
 * create_if_missing : if non-zero, create file if it does not exist
 *
 * Returns NULL on error (errno set).
 */
aw_store_t *aw_store_open(const char *path, int create_if_missing);

/* Close store, free resources. */
void aw_store_close(aw_store_t *st);

/* Begin a transaction using the current store snapshot.
 *
 * Returns NULL on error (errno set).
 * Only one active transaction per store is intended.
 */
aw_tx_t *aw_tx_begin(aw_store_t *st);

/* Add or replace a logical file inside the transaction snapshot.
 *
 * logical_path : UTF-8 path/key, not necessarily a real filesystem path
 * data,len     : full contents to store
 *
 * Returns 0 on success, -1 on error (errno set).
 */
int aw_tx_add_buffer(aw_tx_t *tx,
                     const char *logical_path,
                     const void *data,
                     size_t len);

/* Remove a logical file from the transaction snapshot (if present).
 * Returns 0 on success, -1 on error.
 */
int aw_tx_remove(aw_tx_t *tx, const char *logical_path);

/* Commit transaction: append a new snapshot to the store file.
 * On success, the store's visible state becomes that of this transaction.
 *
 * Returns 0 on success, -1 on error (errno set).
 * On error, the store remains unchanged.
 */
int aw_tx_commit(aw_tx_t *tx);

/* Abort transaction, discard changes. Safe to call multiple times. */
void aw_tx_abort(aw_tx_t *tx);

/* Free transaction object (also aborts if not committed). */
void aw_tx_free(aw_tx_t *tx);

/* Look up a logical file in the current store snapshot.
 *
 * logical_path : key
 * *data_out    : malloc'ed buffer with contents (caller must free),
 * *len_out     : length of buffer.
 *
 * Returns 0 on success, -1 if not found (errno = ENOENT) or on error.
 */
int aw_store_get(aw_store_t *st,
                 const char *logical_path,
                 void **data_out,
                 size_t *len_out);

#endif /* ATOMIC_STORE_H */