class database_ref_t§ Conventions
Everything lives in unum::ustore, and #include <ustore/ustore.hpp> brings in all of it.
Fallible calls return a status_t, a status_code_t beside a static message, or an expected that holds either a value or the status_t explaining its absence; both are [[nodiscard]].
Dereferencing an expected<value_type> yields the value_type, and auto [value, status] decomposes one whose value is default constructible. key_from_integer spells a non-negative integer as a key, and key_after answers the key right after another.
Nothing copies values out of the arena, and nothing throws.
using namespace unum::ustore;
auto [db, status] = database_t::init_ram();
if (status.failed())
std::fprintf(stderr, "%s\n", status.message);database_t::init_ram, open_ram, open_rocksdb, view_rocksdb, open_leveldb and open_nvme wrap the C opens of the same names, taking their argument structs as options.
API
Classdatabase_ref_tThe head of a database as a map from collection names to collections, as the calls on one executor see it, without owning either.19
database_ref_t
operator ustore_database_tThe C handle of the database, so the reference passes as a ustore_database_t.
operator ustore_database_t() const noexcept;receiverThe database and executor this reference runs on, to build another reference on them.
receiver_t receiver() const noexcept;onThe same head, running every call on executor.
database_ref_t on(ustore_executor_t executor) const noexcept;deferredThe same head, whose verbs submit to executor and answer deferred calls.
deferred_database_t deferred(ustore_executor_t executor) const noexcept;describeReports the engine of the database, what it supports and how much it holds.
expected<ustore_database_description_t> describe() noexcept;supports_transactionsWhether the engine runs transactions.
bool supports_transactions() noexcept;transactionBegins a transaction, which runs its calls on this receiver's executor.
expected<transaction_t> transaction() noexcept;snapshotPins a point-in-time view of the database, which the returned snapshot frees when it goes.
expected<snapshot_t> snapshot() noexcept;operator[]Finds the collection named name, or creates it when absent.
expected<blobs_collection_t> operator[](std::string_view name) noexcept;containsWhether a collection named name exists at the head.
expected<bool> contains(std::string_view name) noexcept;collectionsLists the collections at the head, with their identifiers in arena.
expected<collections_list_t> collections(arena_t & arena) noexcept;createCreates a collection holding the modality of collection_type_ under name, which no other collection may carry.
template <typename collection_type_ = blobs_collection_t>
expected<collection_type_> create(std::string_view name) noexcept;findThe collection named name, refusing one that holds another modality than collection_type_.
template <typename collection_type_ = blobs_collection_t>
expected<collection_type_> find(std::string_view name) noexcept;Statuses
status_code_t::not_found_kNo collection carriesname.status_code_t::invalid_argument_kThe collection holds another modality thancollection_type_.
find_or_createThe collection named name, created when no collection carries the name.
template <typename collection_type_ = blobs_collection_t>
expected<collection_type_> find_or_create(
std::string_view name) noexcept;dropDrops the collection name addresses, which takes the name with it.
status_t drop(std::string_view name) noexcept;clearEmpties every collection at once, as mode names.
status_t clear(ustore_drop_mode_t mode) noexcept;Statuses
status_code_t::invalid_argument_kThe RAM and RocksDB engines refuse to drop the collections while a snapshot is open.
compactReclaims the space overwritten and removed data still takes, one collection at a time, reporting its advance to progress, which may cancel it between collections.
status_t compact(progress_arg_t progress = {}) noexcept;flushMakes every commit that returned before this call durable, as if each had asked for ustore_durability_flushed_k.
status_t flush() noexcept;Classdatabase_tA database as a transactional map from collection names to collections of binary values, which owns its handle.10
class database_tIt is thread-safe except for the opens and close, never copies, and outlives the collections it hands out, while its transactions and snapshots may outlive it.
database_t
database_t() noexcept=default;database_t(database_t const &)=delete;database_t(database_t && other) noexcept;database_t(ustore_database_t adopted) noexcept;operator=
database_t & operator=(database_t const &)=delete;database_t & operator=(database_t && other) noexcept;closeDrops this handle, closing the database once no transaction or snapshot of it holds it open.
void close() noexcept;~database_t
~database_t() noexcept;init_ramStarts an empty database of the in-memory engine blocking on executor, or on the calling thread without one.
expected<database_t> init_ram(
ustore_database_init_ram_t options = {},
ustore_executor_t executor = nullptr) noexcept;The database runs its own calls on the calling thread until a receiver names an executor.
open_ramServes the directory options name through the in-memory engine, which persists there as one image, blocking on executor, or on the calling thread without one.
expected<database_t> open_ram(
ustore_database_open_ram_t options,
ustore_executor_t executor = nullptr) noexcept;open_rocksdbServes the directory options name through the RocksDB engine, blocking on executor, or on the calling thread without one.
expected<database_t> open_rocksdb(
ustore_database_open_rocksdb_t options,
ustore_executor_t executor = nullptr) noexcept;view_rocksdbServes the directory options name through the RocksDB engine, read-only, blocking on executor, or on the calling thread without one.
expected<database_t> view_rocksdb(
ustore_database_view_rocksdb_t options,
ustore_executor_t executor = nullptr) noexcept;open_leveldbServes the directory options name through the LevelDB engine, blocking on executor, or on the calling thread without one.
expected<database_t> open_leveldb(
ustore_database_open_leveldb_t options,
ustore_executor_t executor = nullptr) noexcept;open_nvmeServes the directories options name through the NVMe engine on the calling thread, lending it the executor they name until close.
expected<database_t> open_nvme(
ustore_database_open_nvme_t options) noexcept;Functions
bytes_ofThe bytes text spells as an element of a batch, where a missing value and a null string spell empty ones.
template <string_like_concept text_type_>
ustore_bytes_view_t bytes_of(text_type_ const & text) noexcept;