path: root/include/hkvs.h

// SPDX-License-Identifier: LGPL-3.0-or-later

#pragma once
#include <errno.h>
#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

#ifndef HKVS_API
#define HKVS_API extern __attribute__((__nothrow__))
#endif

#ifndef HKVS_INLINE
#define HKVS_INLINE inline static __attribute__((__always_inline__, __unused__, __nothrow__))
#endif

#define HKVS_MUSTCHECK __attribute__((__warn_unused_result__))

#define HKVS_MAGIC ((uint64_t)0xfffec19153564b48ULL)

/* Error codes:
 *  - `-ENOMEM`: Memory allocation failed.
 *  - `-EFBIG`: An implementation limit on the database size has been reached.
 *    Note that this may happen to writes that don't change the number of
 *    records.
 *  - `-EBADMSG`: Database corruption has been detected.
 */

/* ================================================================ */


/*
 * ---------------------- Core Database API -----------------------
 *
 * The database contains a set of tables with 32-bit integer identifiers. Each
 * table contains records with fixed-size keys and variable-sized values.
 *
 * The database storage is provided by an implementation of `hkvs_io`. The core
 * of the database does not provide transaction support. That has to be
 * implemented at the I/O layer.
 */

/* `hkvs*` is the database handle type. */
typedef struct hkvs hkvs;

/* `hkvs_table*` represents a database table. */
typedef struct hkvs_table hkvs_table;

/* `hkvs_io` is an interface for the I/O methods used by the database. */
typedef struct hkvs_io hkvs_io;

/* Open a new database. The database pointer is stored in `*pc`.
 *
 * On failure, a negative error code is returned and `*pc` is left unchanged.
 * The `hkvs_io` is destroyed.
 */
HKVS_API HKVS_MUSTCHECK int hkvs_new(hkvs **pc, hkvs_io *io);

/* Close the database and destroy its `hkvs_io`.
 *
 * This method does not fail. */
HKVS_API void hkvs_free(hkvs *c);

/* Find a table by index. If fewer tables exist, NULL is returned.
 *
 * This method does not fail. */
HKVS_API hkvs_table *hkvs_table_at(hkvs *c, size_t i);

/* Find a table by ID. If no table with the given ID exists or its key size does
 * not match, NULL is returned.
 *
 * This method does not fail. */
HKVS_API hkvs_table *hkvs_table_open(hkvs *c, uint32_t id, size_t key_size);

/* Create a table and store its pointer in `*ptable`. 
 *
 * Record values with size <= `val_size_hint` may be stored together with the
 * key.
 *
 * A positive return value indicates that a table was created, and 0 means that
 * the table already exists.
 *
 * On failure, a negative error code is returned and the database is left
 * unchanged. If a table with the given ID exists but has a different key size,
 * `-EEXIST` is returned. */
HKVS_API int hkvs_table_create(hkvs *c, hkvs_table **ptable, uint32_t id, size_t key_size, size_t val_size_hint);

/* Delete the table with the given ID. A positive return value indicates that a
 * table was found and deleted, and 0 means that no table with the given ID
 * exists.
 *
 * On failure, a negative error code is returned and the database is left
 * unchanged. */
HKVS_API int hkvs_table_delete(hkvs *c, uint32_t id);

/* Get the ID of the given table.
 * 
 * This method does not fail. */
HKVS_API uint32_t hkvs_table_id(hkvs *c, hkvs_table *t);

/* Get the key size of the given table.
 * 
 * This method does not fail. */
HKVS_API size_t hkvs_table_key_size(hkvs *c, hkvs_table *t);

/* Invalidate all record key and value pointers. This may release some
 * resources.
 *
 * This method does not fail. */
HKVS_API void hkvs_put_records(hkvs *c);

/* ================================================================ */


/*
 * -------------------------- Record API --------------------------
 *
 * The record API provides access to the contents of tables.
 *
 * Record IDs are 64-bit integers. New record IDs are assigned either
 * sequentially or by reusing IDs of deleted records.
 *
 * Record IDs are persistent, meaning that a record will keep its ID until
 * deleted.
 */

/* `hkvs_rid` is a wrapper for a record ID. */
typedef struct hkvs_rid hkvs_rid;
struct hkvs_rid {
	uint64_t id;
};

#define HKVS_INVALID_RID ((struct hkvs_rid){(size_t)-1})

/* Check if a record ID is valid. */
HKVS_INLINE bool hkvs_rid_ok(hkvs_rid rid) {
	return rid.id <= UINT64_MAX / 2;
}

/* Return a pointer to the key of the given record, or NULL if no record with
 * that ID exists. The pointer is invalidated by methods that add, remove, or
 * resize records of any table.
 *
 * This method does not fail. */
HKVS_API HKVS_MUSTCHECK const char *hkvs_record_key(hkvs *c, hkvs_table *t, hkvs_rid rid);

/* Get the data pointer and value of the given record. If the record exists,
 * a positive value is returned. If not, 0 is returned.
 *
 * The pointer is invalidated by methods that add, remove, or resize records
 * of any table.  Do not forget to call `hkvs_put_records` when done with the
 * value.
 *
 * On failure, a negative error code is returned. */
HKVS_API HKVS_MUSTCHECK int hkvs_record_value(hkvs *c, hkvs_table *t, hkvs_rid rid, char **pvalue, size_t *psize);

/* Resize a given record. Only the first `min(keep_size, new_size, old_size)`
 * bytes of the value are retained, the rest of the value is uninitialized.
 *
 * If `pvalue` is provided, a pointer to the record value is stored there. Do
 * not forget to call `hkvs_put_records` when done with the value.
 *
 * It is a programmer error to call this method with an ID that does not
 * correspond to an existing record.
 *
 * On failure, a negative error code is returned and the database is left
 * unchanged. */
HKVS_API HKVS_MUSTCHECK int hkvs_record_resize(hkvs *c, hkvs_table *t, hkvs_rid rid, char **pvalue, size_t new_size, size_t keep_size);

/* Find the record with the given key. If no record was found,
 * `HKVS_INVALID_RID` is returned.
 *
 * This method does not fail. */
HKVS_API HKVS_MUSTCHECK hkvs_rid hkvs_record_find(hkvs *c, hkvs_table *t, const char *key);

/* Delete the given record.
 *
 * It is a programmer error to call this method with an ID that does not
 * correspond to an existing record.
 *
 * This method does not fail. */
HKVS_API void hkvs_record_delete(hkvs *c, hkvs_table *t, hkvs_rid rid);

/* Append a new record to the table. The ID of the new record is stored in
 * `*prid`.
 *
 * It is a programmer error to call this method with a key that is already in
 * the table.
 *
 * On failure, a negative error code is returned and the database is left
 * unchanged. */
HKVS_API HKVS_MUSTCHECK int hkvs_record_append(hkvs *c, hkvs_table *t, hkvs_rid *prid, const char *key, char **pvalue, size_t size);

/* ================================================================ */


/*
 * ---------------------- Utility Functions -----------------------
 *
 * These are some utility functions that can be correctly implemented using
 * the rest of the public API. However, the implementations provided here may be
 * slightly more efficient.
 */

/* Set the value of a record.
 *
 * It is a programmer error to call this method with a record ID that does not
 * correspond to an existing record.
 *
 * On failure, a negative error code is returned and the database is left
 * unchanged. */
HKVS_API HKVS_MUSTCHECK int hkvs_record_set(hkvs *c, hkvs_table *t, hkvs_rid rid, const char *value, size_t size);

/* Append or set the record with the given key.
 *
 * The ID of the record is stored in `*prid`. If a new record was created, 1
 * is returned. If an existing record was changed, 0 is returned.
 *
 * On failure, a negative error code is returned and the database is left
 * unchanged. */
HKVS_API HKVS_MUSTCHECK int hkvs_record_update(hkvs *c, hkvs_table *t, hkvs_rid *prid, const char *key, const char *value, size_t size);

/* ================================================================ */


/*
 * ------------------------- Iterator API -------------------------
 *
 * An iterator provides a way to enumerate all records in a table. Iterators
 * themselves do not consume any resources.
 *
 * The fields of `hkvs_iter` are an implementation detail.
 */
typedef struct hkvs_iter hkvs_iter;
struct hkvs_iter {
	size_t priv1, priv2;
};

/* Initialize an iterator. The first call to `hkvs_iter_next` on the iterator
 * will return the first record. Any change of the database invalidates the
 * iterator, and it must be reinitialized.
 *
 * This method does not fail.
 */
HKVS_API void hkvs_iter_open(hkvs *c, hkvs_table *t, hkvs_iter *it);

/* Initialize an iterator positioned at a given record. The next call to
 * `hkvs_iter_next()` will return the first record with an ID greater than
 * or equal to the one given here.
 *
 * This method does not fail. */
HKVS_API void hkvs_iter_seek(hkvs *c, hkvs_table *t, hkvs_iter *it, hkvs_rid rid);

/* Retrieve the ID of the next record. If `pkey` is provided, a pointer to the
 * record's key is stored there.
 *
 * If the end of the database has been reached, `HKVS_INVALID_RID` is returned.
 *
 * This method does not fail. */
HKVS_API HKVS_MUSTCHECK hkvs_rid hkvs_iter_next(hkvs *c, hkvs_table *t, hkvs_iter *it, const char **pkey);

/* Delete the record last returned by `hkvs_iter_next()` without invalidating
 * the iterator. Key and value pointers are still invalidated.
 *
 * It is a programmer error to call this method without a preceding call to
 * `hkvs_iter_next()`.
 *
 * This method does not fail. */
HKVS_API void hkvs_iter_delete(hkvs *c, hkvs_table *t, hkvs_iter *it);

/* ================================================================ */


/*
 * ------------------------- hkvs_io API --------------------------
 *
 * The I/O interface consists of several methods for operating on memory-mapped
 * files.
 *
 * In order to initialize the database, an empty file 0 must be created. It will
 * never be deleted.
 */

struct hkvs_io {
	/* Destroy the IO interface. */
	void (*destroy)(hkvs_io *io);

	/* Write random bytes to the given buffer. */
	int (*random)(hkvs_io *io, char *buf, size_t size);

	/* Open the file and memory-map it. The size is stored in `*psz` and the
	 * address is stored in `*pmem`. The file is not open when this method is
	 * called. */
	int (*open)(hkvs_io *io, uint64_t fi, char **pmem, size_t *psz);

	/* Create a zero-filled file with the given size and open it. */
	int (*create)(hkvs_io *io, uint64_t *pfi, char **pmem, size_t sz);

	/* Resize the file and update its memory-mapped address. The file is open
	 * and mapped at `*pmem` with size `old_sz` when this method is called. */
	int (*resize)(hkvs_io *io, uint64_t fi, char **pmem, size_t old_sz, size_t new_sz);

	/* Release the file's memory mapping and close it. The file is open and
	 * mapped at `mem` with size `sz` when this method is called. */
	void (*close)(hkvs_io *io, uint64_t fi, char *mem, size_t sz);

	/* Delete the file. The file is not open when this method is called. */
	void (*unlink)(hkvs_io *io, uint64_t fi);
};

/* Create a new `hkvs_io` that entirely works in memory. */
HKVS_API hkvs_io *hkvs_io_new_mem(uint64_t random_seed);

/* Create a new `hkvs_io` given a directory file descriptor. This implementation
 * is simple but it does no locking and is not crash-safe. */
HKVS_API hkvs_io *hkvs_io_new_unsafe_dirfd(int fd);

/* ================================================================ */