Implexus/vapi/lmdb.vapi

/**
 * LMDB - Lightning Memory-Mapped Database bindings for Vala
 * 
 * This VAPI provides bindings for the LMDB library,
 * a high-performance key-value store with ACID transactions.
 */
[CCode (cprefix = "mdb_", lower_case_cprefix = "mdb_", cheader_filename = "lmdb.h")]
namespace Lmdb {

    /**
     * Environment flags for mdb_env_open()
     */
    [CCode (cname = "unsigned int", has_type_id = false)]
    [Flags]
    public enum EnvFlags {
        [CCode (cname = "0")]
        NONE,
        [CCode (cname = "MDB_FIXEDMAP")]
        FIXEDMAP,
        [CCode (cname = "MDB_NOSUBDIR")]
        NOSUBDIR,
        [CCode (cname = "MDB_NOSYNC")]
        NOSYNC,
        [CCode (cname = "MDB_RDONLY")]
        RDONLY,
        [CCode (cname = "MDB_NOMETASYNC")]
        NOMETASYNC,
        [CCode (cname = "MDB_WRITEMAP")]
        WRITEMAP,
        [CCode (cname = "MDB_MAPASYNC")]
        MAPASYNC,
        [CCode (cname = "MDB_NOTLS")]
        NOTLS,
        [CCode (cname = "MDB_NOLOCK")]
        NOLOCK,
        [CCode (cname = "MDB_NORDAHEAD")]
        NORDAHEAD,
        [CCode (cname = "MDB_NOMEMINIT")]
        NOMEMINIT
    }

    /**
     * Transaction flags for mdb_txn_begin()
     */
    [CCode (cname = "unsigned int", has_type_id = false)]
    [Flags]
    public enum TxnFlags {
        [CCode (cname = "0")]
        NONE,
        [CCode (cname = "MDB_RDONLY")]
        RDONLY
    }

    /**
     * Database flags for mdb_dbi_open()
     */
    [CCode (cname = "unsigned int", has_type_id = false)]
    [Flags]
    public enum DbFlags {
        [CCode (cname = "0")]
        NONE,
        [CCode (cname = "MDB_REVERSEKEY")]
        REVERSEKEY,
        [CCode (cname = "MDB_DUPSORT")]
        DUPSORT,
        [CCode (cname = "MDB_INTEGERKEY")]
        INTEGERKEY,
        [CCode (cname = "MDB_DUPFIXED")]
        DUPFIXED,
        [CCode (cname = "MDB_INTEGERDUP")]
        INTEGERDUP,
        [CCode (cname = "MDB_REVERSEDUP")]
        REVERSEDUP,
        [CCode (cname = "MDB_CREATE")]
        CREATE
    }

    /**
     * Write flags for mdb_put()
     */
    [CCode (cname = "unsigned int", has_type_id = false)]
    [Flags]
    public enum WriteFlags {
        [CCode (cname = "0")]
        NONE,
        [CCode (cname = "MDB_NOOVERWRITE")]
        NOOVERWRITE,
        [CCode (cname = "MDB_NODUPDATA")]
        NODUPDATA,
        [CCode (cname = "MDB_CURRENT")]
        CURRENT,
        [CCode (cname = "MDB_RESERVE")]
        RESERVE,
        [CCode (cname = "MDB_APPEND")]
        APPEND,
        [CCode (cname = "MDB_APPENDDUP")]
        APPENDDUP,
        [CCode (cname = "MDB_MULTIPLE")]
        MULTIPLE
    }

    /**
     * Cursor operation codes for mdb_cursor_get()
     */
    [CCode (cname = "MDB_cursor_op", has_type_id = false)]
    public enum CursorOp {
        [CCode (cname = "MDB_FIRST")]
        FIRST,
        [CCode (cname = "MDB_FIRST_DUP")]
        FIRST_DUP,
        [CCode (cname = "MDB_GET_BOTH")]
        GET_BOTH,
        [CCode (cname = "MDB_GET_BOTH_RANGE")]
        GET_BOTH_RANGE,
        [CCode (cname = "MDB_GET_CURRENT")]
        GET_CURRENT,
        [CCode (cname = "MDB_GET_MULTIPLE")]
        GET_MULTIPLE,
        [CCode (cname = "MDB_LAST")]
        LAST,
        [CCode (cname = "MDB_LAST_DUP")]
        LAST_DUP,
        [CCode (cname = "MDB_NEXT")]
        NEXT,
        [CCode (cname = "MDB_NEXT_DUP")]
        NEXT_DUP,
        [CCode (cname = "MDB_NEXT_MULTIPLE")]
        NEXT_MULTIPLE,
        [CCode (cname = "MDB_NEXT_NODUP")]
        NEXT_NODUP,
        [CCode (cname = "MDB_PREV")]
        PREV,
        [CCode (cname = "MDB_PREV_DUP")]
        PREV_DUP,
        [CCode (cname = "MDB_PREV_NODUP")]
        PREV_NODUP,
        [CCode (cname = "MDB_SET")]
        SET,
        [CCode (cname = "MDB_SET_KEY")]
        SET_KEY,
        [CCode (cname = "MDB_SET_RANGE")]
        SET_RANGE,
        [CCode (cname = "MDB_PREV_MULTIPLE")]
        PREV_MULTIPLE
    }

    /**
     * LMDB error codes
     */
    [CCode (cname = "int", has_type_id = false)]
    public enum ErrorCode {
        [CCode (cname = "MDB_SUCCESS")]
        SUCCESS,
        [CCode (cname = "MDB_KEYEXIST")]
        KEYEXIST,
        [CCode (cname = "MDB_NOTFOUND")]
        NOTFOUND,
        [CCode (cname = "MDB_PAGE_NOTFOUND")]
        PAGE_NOTFOUND,
        [CCode (cname = "MDB_CORRUPTED")]
        CORRUPTED,
        [CCode (cname = "MDB_PANIC")]
        PANIC,
        [CCode (cname = "MDB_VERSION_MISMATCH")]
        VERSION_MISMATCH,
        [CCode (cname = "MDB_INVALID")]
        INVALID,
        [CCode (cname = "MDB_MAP_FULL")]
        MAP_FULL,
        [CCode (cname = "MDB_DBS_FULL")]
        DBS_FULL,
        [CCode (cname = "MDB_READERS_FULL")]
        READERS_FULL,
        [CCode (cname = "MDB_TLS_FULL")]
        TLS_FULL,
        [CCode (cname = "MDB_TXN_FULL")]
        TXN_FULL,
        [CCode (cname = "MDB_CURSOR_FULL")]
        CURSOR_FULL,
        [CCode (cname = "MDB_PAGE_FULL")]
        PAGE_FULL,
        [CCode (cname = "MDB_MAP_RESIZED")]
        MAP_RESIZED,
        [CCode (cname = "MDB_INCOMPATIBLE")]
        INCOMPATIBLE,
        [CCode (cname = "MDB_BAD_RSLOT")]
        BAD_RSLOT,
        [CCode (cname = "MDB_BAD_TXN")]
        BAD_TXN,
        [CCode (cname = "MDB_BAD_VALSIZE")]
        BAD_VALSIZE,
        [CCode (cname = "MDB_BAD_DBI")]
        BAD_DBI,
        [CCode (cname = "MDB_LAST_ERRCODE")]
        LAST_ERRCODE
    }

    /**
     * Key/value structure
     */
    [CCode (cname = "MDB_val", has_type_id = false)]
    public struct Val {
        public size_t mv_size;
        public void* mv_data;

        /**
         * Creates a Val from a string.
         */
        public static Val from_string(string str) {
            Val val = Val();
            val.mv_size = str.length;
            val.mv_data = (void*) str;
            return val;
        }

        /**
         * Creates a Val from binary data.
         */
        public static Val from_bytes(uint8[] data) {
            Val val = Val();
            val.mv_size = data.length;
            val.mv_data = (void*) data;
            return val;
        }

        /**
         * Gets the value as a string.
         * Creates a new string with proper null termination.
         */
        public string as_string() {
            if (mv_data == null || mv_size == 0) {
                return "";
            }
            // Create a new string with proper length and null termination
            // We allocate mv_size + 1 bytes and copy the data
            uint8[] data = new uint8[mv_size + 1];
            GLib.Memory.copy(data, mv_data, mv_size);
            data[mv_size] = 0; // null terminator
            return (string) data;
        }

        /**
         * Gets the value as a uint8 array.
         */
        public uint8[] as_bytes() {
            uint8[] data = new uint8[mv_size];
            GLib.Memory.copy(data, mv_data, mv_size);
            return data;
        }
    }

    // Database handle - just an unsigned int in C (MDB_dbi)
    // We use uint directly since it's a typedef for unsigned int

    /**
     * Environment handle - opaque pointer
     */
    [Compact]
    [CCode (cname = "MDB_env", free_function = "mdb_env_close")]
    public class Env {
        /**
         * Creates a new LMDB environment.
         * 
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_env_create")]
        public static int create(out Env env);

        /**
         * Opens an environment.
         * 
         * @param path Directory path for the database files
         * @param flags Environment flags
         * @param mode File mode for created files
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_env_open")]
        public int open(string path, uint flags, int mode);

        /**
         * Sets the size of the memory map.
         * 
         * @param size Size in bytes
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_env_set_mapsize")]
        public int set_mapsize(size_t size);

        /**
         * Sets the maximum number of databases.
         * 
         * @param dbs Maximum number of databases
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_env_set_maxdbs")]
        public int set_maxdbs(uint32 dbs);

        /**
         * Sets the maximum number of readers.
         * 
         * @param readers Maximum number of readers
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_env_set_maxreaders")]
        public int set_maxreaders(uint32 readers);

        /**
         * Flushes data buffers to disk.
         * 
         * @param force If true, force a synchronous flush
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_env_sync")]
        public int sync(bool force);
    }

    /**
     * Transaction handle - opaque pointer
     */
    [Compact]
    [CCode (cname = "MDB_txn", free_function = "")]
    public class Txn {
        /**
         * Begins a new transaction.
         * 
         * @param env Environment handle
         * @param parent Parent transaction (null for none)
         * @param flags Transaction flags
         * @param txn Output transaction handle
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_txn_begin")]
        public static int begin(Env env, Txn? parent, uint flags, out Txn txn);

        /**
         * Commits the transaction.
         * 
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_txn_commit")]
        public int commit();

        /**
         * Aborts the transaction.
         */
        [CCode (cname = "mdb_txn_abort")]
        public void abort();

        /**
         * Gets the environment for this transaction.
         * 
         * @return Environment handle
         */
        [CCode (cname = "mdb_txn_env")]
        public unowned Env env();

        /**
         * Opens a database in the transaction.
         * 
         * @param name Database name (null for default)
         * @param flags Database flags
         * @param dbi Output database handle
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_dbi_open")]
        public int dbi_open(string? name, uint flags, out uint dbi);

        /**
         * Gets a value from the database.
         * 
         * @param dbi Database handle
         * @param key Key to look up
         * @param data Output value
         * @return 0 on success, MDB_NOTFOUND if key not found
         */
        [CCode (cname = "mdb_get")]
        public int @get(uint dbi, Val* key, Val* data);

        /**
         * Puts a key-value pair into the database.
         * 
         * @param dbi Database handle
         * @param key Key
         * @param data Value
         * @param flags Write flags
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_put")]
        public int @put(uint dbi, Val* key, Val* data, uint flags);

        /**
         * Deletes a key from the database.
         * 
         * @param dbi Database handle
         * @param key Key to delete
         * @param data Optional data to match (null for any)
         * @return 0 on success, MDB_NOTFOUND if key not found
         */
        [CCode (cname = "mdb_del")]
        public int del(uint dbi, Val* key, Val* data);
    }

    /**
     * Cursor handle - opaque pointer
     */
    [Compact]
    [CCode (cname = "MDB_cursor", free_function = "mdb_cursor_close")]
    public class Cursor {
        /**
         * Creates a new cursor.
         * 
         * @param txn Transaction handle
         * @param dbi Database handle
         * @param cursor Output cursor handle
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_cursor_open")]
        public static int open(Txn txn, uint dbi, out Cursor cursor);

        /**
         * Gets a key/value pair from the cursor.
         * 
         * @param key Output key
         * @param data Output value
         * @param op Cursor operation
         * @return 0 on success, MDB_NOTFOUND if no more items
         */
        [CCode (cname = "mdb_cursor_get")]
        public int @get(Val* key, Val* data, CursorOp op);

        /**
         * Puts a key/value pair through the cursor.
         * 
         * @param key Key
         * @param data Value
         * @param flags Write flags
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_cursor_put")]
        public int @put(Val* key, Val* data, uint flags);

        /**
         * Deletes the current key/value pair.
         * 
         * @param flags Delete flags
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_cursor_del")]
        public int del(uint flags);

        /**
         * Gets the count of duplicates for the current key.
         * 
         * @param countp Output count
         * @return 0 on success, error code on failure
         */
        [CCode (cname = "mdb_cursor_count")]
        public int count(out size_t countp);
    }

    /**
     * Gets a string describing an error code.
     * 
     * @param err Error code
     * @return Error description string
     */
    [CCode (cname = "mdb_strerror")]
    public unowned string strerror(int err);

    /**
     * Gets the version of the LMDB library.
     * 
     * @param major Output major version
     * @param minor Output minor version
     * @param patch Output patch version
     * @return Version string
     */
    [CCode (cname = "mdb_version")]
    public unowned string version(out int major, out int minor, out int patch);
}