C

UStore for C

GIT_REPOSITORY https://github.com/unum-cloud/UStore.git 1.0.0-rc.1 · d6d40961

c/ is the public C SDK of UStore, and its only interface: every engine and every binding meets here. The *.h headers declare a C11 binary interface that every engine implements — the in-memory ram reference engine, the RocksDB and LevelDB key-value stores, and the NVMe engine as a v1 target — so any language with a C FFI can drive the database. UStore’s sources split into four folders:

  • c/: this SDK, the C ABI in c/ustore/*.h, test.c, which compiles it as plain C11 against both libraries, and this guide.
  • cpp/: the C++ wrappers of the same calls in cpp/ustore/*.hpp, in unum::ustore, with their own guide.
  • include/: reserved for the first-party classes and templates that advanced users may reuse to build their own low-level stores, each subfolder ustore/<dir>/ opening unum::ustore::<dir>.
  • src/: UStore’s own instantiations of those templates, the engines behind this C ABI.

c/ustore/ holds one header per part of the interface:

  • ustore.h: every C header below.
  • types.h: statuses, outcomes, completions, progress callbacks, executors, arenas, string batches and the version.
  • db.h: databases, collections, snapshots, transactions, views, strided runs of keys and enum spellings.
  • blobs.h: binary values, through ustore_blobs_write, _remove, _read, _scan, _sample, _measure and cursors.
  • strings.h: string-keyed values, through ustore_strings_write, _remove, _read, _scan, _sample, _measure and cursors.
  • docs.h: JSON documents, through ustore_docs_write, _read, _gist, _gather, _remove, _scan, _sample and _measure.
  • graph.h: graph edges and vertices, and the scans, samples and measures of the vertices.
  • pages.h: ordered documents, through one verb per edit, ustore_pages_read, _scan, _sample and _measure.

Every verb serves only collections of its own modality, and answers ustore_status_invalid_argument_k for a collection holding another.

Topics

Installation5
Quickstart14Every 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.
Collections19A database holds no collection until one is created, and every call names the collections it addresses, refusing a collections view with NULL data with ustorestatusinvalidargumentk.
Reads and Writes29
Scans32
Batches and Arenas28An executor owns the threads that run calls and the scratch they use, and a NULL executor runs a call on the calling thread.
Transactions11A transaction groups reads and writes across collections and modalities, and commits all of them or none.
Snapshots5
Documents9A document collection stores JSON text, so reading a document back through ustoreblobsread may not return the exact bytes written.
Graphs17A graph collection stores edges as triplets of a source, a target and an edge identifier, indexed from both ends.
Errors1
Platform Notes10A strings collection, created with ustoremodalitystringsk, keys its values by variable-length strings, kept in the order of their bytes.