#if !defined(__KVMGR_H__)

#define __KVMGR_H__ 1

#include "htab.h"
#include "mylock.h"
#include "xce/types.h"
#include "xlist.h"
#include "zarray.h"
#include "persist.h"

typedef enum {
    KVMGR_KEY_INT = 0,
    KVMGR_KEY_STRING
} kvmgr_key_type_t;

typedef struct {
    kvmgr_key_type_t key_type;
    uint32_t         nslots;
    uint32_t         delta;
    destroy_fn_t     datakiller;
} kvmgr_params_t;

extern typeinfo_t xkvmgr_type;

/*
 * kvmgr_capture_keys — capture key→index mappings for checkpoint
 * serialization (Part 3.8).
 *
 * Caller MUST hold the kvmgr write lock for the full duration of
 * this call.  The function allocates *keys_out and populates it with
 * *n_keys_out entries.  Each entry's key[] field is an owned deep
 * copy that remains valid after the write lock is released.
 *
 * Caller must free(*keys_out) when done.
 *
 * Returns  0 on success.
 * Returns -ENOMEM if allocation fails.
 */
int kvmgr_capture_keys(var          kvmgr,
                       slot_key_t** keys_out,
                       size_t*      n_keys_out);

/*
 * kvmgr_reserve — job-array-single-wal-record task 7.1 (bug-1443).
 *
 * Pre-grows kvmgr's backing value store (the internal xzarray_type
 * instance) for `n` additional entries, via the new xzarray_reserve()
 * primitive (zarray.h/zarray.c) -- zero changes to any existing function in
 * either file. Closes the DOMINANT, N-scaling failure mode for a bulk
 * key_add() loop (e.g. restore_job_array()'s bulk-insert pass, job.c): the
 * large realloc() reachable through key_add -> xkvmgr_add -> vstore ->
 * xzarray_ensure_items when the value store must grow.
 *
 * This narrows, but does NOT eliminate, that failure surface: key_add()'s
 * own kvtab_add() call (kv.c) still has its own separate, tiny per-entry
 * hash-chain-node allocation, and a content-based -EEXIST collision remains
 * theoretically possible -- both are far rarer and non-N-scaling compared
 * to the growth cycle this call structurally avoids.
 *
 * Caller MUST hold the kvmgr write lock for the full duration of this call
 * -- identical contract to kvmgr_capture_keys() above.
 *
 * Returns 1 on success (capacity already sufficient, or successfully
 * grown). Returns -EINVAL for a NULL kvmgr or negative n. Returns -ENOMEM
 * if the underlying growth allocation fails.
 */
int kvmgr_reserve(var kvmgr, int n);

#endif