Quickstart

§ Conventions

Every call takes a single pointer to an argument struct named after it with a _t suffix, so arguments are named and every omitted one is zero. Every struct opens with its handle, then executor, outcome and completion, so every call reports through a ustore_outcome_t whose status names the result and whose static message is never freed. Statuses read ustore_status_<name>_k, from ustore_status_success_k through every failure. Every closed set is a C enum, and each one a binding spells has a pair of functions: <prefix>_<enum>_name, such as ustore_isolation_name, answers a static lowercase spelling like strict-serializable, or unrecognized for a value no enumerator carries, and <prefix>_<enum>_from_name reads a ustore_bytes_view_t back into its output, failing with ustore_status_invalid_argument_k for a name it does not know. ustore_version_name spells the version of the library the program runs against, like 1.0.0. Every call is a batch of count tasks, and each of its inputs takes one of three shapes:

• One run of bytes, a ustore_bytes_view_t of a pointer and a length, carries a path or a name, never null-terminated by contract.
• A strided run of fixed-width elements, such as a ustore_keys_view_t of a pointer and a stride in bytes, carries one element per task, and a zero stride repeats the first element for every task.
• A ragged batch, a ustore_strings_view_t, carries one string per task as an Apache Arrow tape of 32-bit or 64-bit offsets, or through an accessor callback over any other shape.

A zeroed view of any shape stands for the input’s default. Every output whose length scales with the call lands packed in the arena the call is given, so no output carries a capacity or a stride, and ragged bytes come back as a tape. Keys are ustore_key_t, 16 bytes of a UUID compared bytewise, and a non-negative integer spells as its 128-bit big-endian bytes, as Python’s uuid.UUID(int=...) does, so keys made from integers order as the integers.

The examples below share these handles, the arena made once for calls on the calling thread:

ustore_database_t database = NULL;
ustore_executor_t executor = NULL;
ustore_outcome_t outcome = {0};
ustore_arena_t arena = NULL;
ustore_arena_init(&(ustore_arena_init_t){.arena = &arena, .outcome = &outcome});

§ Opening the Database

#include <ustore/ustore.h>

char const directory[] = "/var/lib/ustore";
ustore_database_open_rocksdb(&(ustore_database_open_rocksdb_t){
    .database = &database,
    .outcome = &outcome,
    .directory = {(uint8_t const*)directory, sizeof(directory) - 1},
});
if (outcome.status != ustore_status_success_k)
    fprintf(stderr, "%s: %s\n", ustore_status_name(outcome.status), outcome.message);

ustore_arena_free(arena);
ustore_database_free(database);
ustore_executor_free(executor);

Each engine opens through its own calls, whose arguments hold what that engine can be asked, and a zero field keeps the engine’s default:

• ustore_database_init_ram starts an empty database in memory alone, while ustore_database_open_ram serves a directory as one image, loading it at open and rewriting it whole on a flushed commit and on close.
• ustore_database_open_rocksdb and ustore_database_open_leveldb serve a directory in place, creating the database when the directory holds none.
• ustore_database_open_nvme serves the database its manifest names, <database>.ustore.json in an existing directory or the raw address of its first slot, such as /dev/nvme0n1@64GiB, creating the database when the manifest is absent.
• ustore_database_view_rocksdb serves an existing RocksDB directory read-only, refusing every call that would change it with ustore_status_read_only_k: writes, removes, transactions, collection creates and drops, clears and compactions, while snapshots and their saves still serve.

The opens of an engine the build lacks answer ustore_status_unsupported_k, so a program links against every build. Every freeing function accepts NULL.