Module common 

Common Components

This module provides common components and utilities used throughout the vsdb crate. It re-exports items from vsdb_core::common (including the error module — the unified error vocabulary of the whole ecosystem) and includes the ende module for encoding and decoding traits.

Modules

ende

A module for encoding and decoding traits.

error

Structured error types for the VSDB public API.

namespace

Namespaces: anonymous placement groups (independent engine instances).

Structs

InstanceId

The complete public identity of a collection instance — the same shape at every layer: in-memory comparison, the persisted meta bytes, and this token. ns: None ⇔ default namespace ⇔ the 16-byte meta form; a bare u64 converts losslessly (From<u64> ⇒ ns: None).

Namespace

A cheap, cloneable handle to an engine instance (an anonymous placement group). See the module docs for the design rules.

NamespaceOpts

Creation-time options; persisted in the registry. Everything is defaulted — this struct exists for the advanced tier.

NsInfo

A registry entry as reported by vsdb_ns_list.

VsDB

A struct representing the VsDB database.

Constants

BIGGEST_RESERVED_ID

The biggest reserved ID.

DEFAULT_NS_ID

The default namespace’s id — a fixed constant, never allocated, never present in the registry, never looked up.

GB

A constant representing 1 gigabyte in bytes.

KB

A constant representing 1 kilobyte in bytes.

MB

A constant representing 1 megabyte in bytes.

PREFIX_SIZE

The size of a prefix in bytes.

Statics

VSDB

The global instance of the VsDB database.

Traits

BatchTrait

Trait for batch write operations

Functions

atomic_write_file

Atomically replaces the file at path with bytes.

load_instance_meta

Reads the meta file for id and deserializes it back.

save_instance_meta

Serializes value with postcard and writes it to the owning namespace’s instance-meta directory under id.map_id.

vsdb_flush

Flushes all data to disk — the default namespace and every open non-default namespace.

vsdb_get_base_dir

Returns the base directory path for VSDB.

vsdb_get_custom_dir

Returns the custom directory path for VSDB — the app-level bootstrap anchor, deliberately one per universe (NOT per namespace).

vsdb_get_meta_dir

Returns the instance-meta directory path of the default namespace (its root is the base dir, so this equals Namespace::default_ns().meta_dir(); non-default namespaces keep their metas under their own roots — use Namespace::meta_dir).

vsdb_get_system_dir

Returns the internal system directory path of the default namespace (≡ Namespace::default_ns().system_dir(); each namespace has its own __SYSTEM__ under its root — see Namespace::system_dir). Also home to the registry-wide state that deliberately stays global: the namespace registry, the prefix allocator ceiling, and the DagMap ID counter.

vsdb_meta_path

Returns the default-namespace meta file path for a given map ID (a bare u64 can only ever address a default-namespace instance; namespace-resident metas live under Namespace::meta_dir).

vsdb_ns_close

Closes an open namespace, releasing all of its resources: engine memory, compaction threads, fds, and mmdb LOCK files. The active memtables are flushed and the WALs synced first (errors surface here, unlike a plain drop).

vsdb_ns_destroy

Destroys a namespace: removes its registry entry, then deletes its whole directory tree — O(1) bulk reclaim.

vsdb_ns_list

Lists every registered (non-default) namespace.

vsdb_ns_relocate

Re-points a namespace at a new root directory (e.g. after moving a volume). Updates the registry only — moving the data is the operator’s job, done before calling this. A target that does not already hold an initialized dataset (format marker + per-shard engine anchors) is refused: repointing at it would durably orphan the real data behind a silent success. Whether it is the right dataset cannot be verified — roots carry no namespace id.

vsdb_set_base_dir

Sets the base directory path for VSDB manually.

Type Aliases

NsId

A namespace identifier: small, stable, allocated once at creation, never reused.

Pre

A type alias for a prefix, represented as a u64.

PreBytes

A type alias for a prefix represented as a byte array.

RawBytes

A type alias for a vector of bytes, commonly used for raw data.

RawKey

A type alias for a raw key, represented as a vector of bytes.

RawValue

A type alias for a raw value, represented as a vector of bytes.