Expand description
§bstack_raii
A typed, RAII-style ownership, lifetime, and on-disk-layout layer built on
top of the mainline bstack alloc primitives (bstack::BStackRange,
bstack::BStackSlice, bstack::BStackOwnedSlice). It decouples
disk-level destruction (BStackDrop) from Rust’s process-scoped Drop,
providing persistent-storage ownership with C++-style unique_ptr /
shared_ptr / weak_ptr conveniences.
It is a separate crate (not a bstack feature) so that its large, not-yet-stable
ABI surface never gates bstack’s ABI stability.
§Module map (bottom-up)
| Module | Contents |
|---|---|
layout | On-disk primitives: EightCC, BlockHeader (both Pod). |
reference | BStackRef: typed range wrapper + buffered OnDisk read. |
teardown | BStackDrop trait, AutoDrop RAII guard, dealloc_range. |
handback | The hand-back error family: ConstructError, ReplaceError, CastError, IntoLocalError + the HandBack trait. |
block | Block-type contracts: BStackCast, BStackBlock, BStackWeakable. |
refcount | Little-endian atomic CAS ops over on-disk u64 counters. |
bulk | Sequential fallbacks for BStackRaiiAllocator::alloc_many / free_many; bulk allocators override those trait methods. |
clone | TryClone / TryCloneIn: fallible clone for handles that touch disk. |
owned | BStackOwned + the OwnedRef without-allocator drop core. |
shared | BStackRc / BStackWeak + the StrongRef / StrongWeakRef / WeakRef drop cores. |
cast | Typed ↔ untyped handle conversion — the runtime behind bstack_cast!. |
vec | VecDesc-backed growable vectors reached through a fixed-size field. |
[registry] | Process-wide path↔FileId registry underlying Foreign<T>. |
traits::foreign / compiled::foreign / io_core::foreign | Foreign<T> cross-file pointer, its ForeignOwned/ForeignRc/ForeignWeak handles, and the cross-file teardown/clone mechanism. |
wal | Write-ahead log for atomic multi-slice transactions and leak reclamation. |
stdlib | Ergonomic handle/collection types built entirely on the above (e.g. BStackHashMap, BStackDeque, BStackCow). |
§Conventions fixed by the ABI
- All on-disk multi-byte integers (refcounts, offsets) are little-endian,
matching
bstack’s own on-disk format. - Reads are buffer-based (
read_into+bytemuck::from_bytes); there is no zero-copy path withoutmmap. - The whole layer speaks
std::io::Result/std::io::Error, a consequence of binding allocators tobstack::BStackOwnedSliceAllocator(which pinsError = io::ErrorandAllocated<'a> = BStackOwnedSlice).
§Status
Feature-complete: the runtime primitives, the procedural macros
(bstack_block, bstack_enum, bstack_move,
bstack_cast), and the stdlib collection suite are all implemented and
exercised by the test suite. The main open gap is Foreign<T> cross-file
deep-clone/teardown dispatch, which is still deferred (a Foreign field is
byte-copied on clone and freed by nobody on teardown regardless of its
ownership annotation) — see the Foreign type’s module docs.
Re-exports§
pub use bytemuck;
Modules§
- rtti
- Runtime Type Information: a persisted, self-describing schema stack for
interpreting
bstack_raiistructures on disk with no compiled-in types. Runtime Type Information (RTTI) — a persisted, self-describing schema stack.
Macros§
- bstack_
cast bstack_cast!(expr as Target)— type-checked handle conversion. The target is given explicitly (a function-like macro can’t read aletannotation) and selects the direction:- bstack_
move bstack_move!(handle)/bstack_move!(owned, allocator)— transfer every field out of a block, freeing only the parent shell.- rtti_
path - Build an RTTI field path from dotted field names for
get/set/swap:rtti_path!(outer.inner.leaf)expands to&["outer", "inner", "leaf"], and a single namertti_path!(field)to&["field"]. The result is a&[&str], so it drops straight into the path argument.
Structs§
- Auto
Drop - A guard that runs
BStackDrop::bstack_dropon its inner handle when it goes out of scope, bridging fallible on-disk teardown to Rust’sDrop. - BStack
- A persistent, fsync-durable binary stack backed by a single file.
- BStackB
Tree Map - An owned, ordered map backed by a copy-on-write B-tree.
- BStackB
Tree Set - An owned ordered set of
Pod + Ordkeys with an embedded Bloom filter. - BStack
Binary Heap - An owned binary min-heap of
(K, V)entries. - BStack
Block Vec - A persistent, growable vector of owned block children.
- BStack
Box - An owned, single-value block wrapping a plain
PodT. - BStack
Counting Bloom Filter - An owned counting Bloom filter over
Podkeys. - BStack
Deque - An owned double-ended queue of
Tblocks. - BStack
Hash Map - An owned open-addressing hash map from a
Podkey to a block value. - BStack
Hash Set - An owned open-addressing set of
Podkeys with an embedded Bloom filter. - BStack
Linked List - An owned, doubly-linked list of
Tblocks. - BStack
Owned - A uniquely-owned handle to a block: an ownership marker over an inner
BStackDrophandle whose teardown recursively frees the block on disk. - BStack
Range - A raw
(offset, len)coordinate pair with no backing reference. - BStack
Rc - A shared, refcounted, allocator-bound handle.
- BStack
Ref - A typed reference to a block of type
T. - BStack
RefVec - A persistent, growable vector of raw references to block children.
- BStack
Slice - A borrowed, non-owning view of a contiguous region within a
BStackpayload. - BStack
String - A standalone owned UTF-8 string block.
- BStack
Strong Vec - A persistent, growable vector of strong references to shared block
children (
(rc)/(rc, weak)blocks). - BStack
Vec - A persistent, growable vector of POD elements. Backs un-annotated
Vec<T>(T: Pod) /Stringfields. - BStack
Weak - A non-owning weak handle to an
(rc, weak)block’s control block. - BStack
Weak Vec - A persistent, growable vector of weak references to
(rc, weak)block children. - BTree
MapIter - A lazy in-order iterator over a
BStackBTreeMap, yieldingio::Result<(K, V)>in ascending key order. Created byBStackBTreeMap::iter/BStackBTreeMap::range; borrows theBStackfor its lifetime and reads nodes on demand. - BTree
SetIter - A lazy in-order iterator over a
BStackBTreeSet, yieldingio::Result<K>in ascending order. Created byBStackBTreeSet::iter/BStackBTreeSet::range. - Block
Header - The header prefixing every on-disk block. 16 bytes.
- Bloom
OnDisk - The on-disk image of a
BStackCountingBloomFilter: header, counter-array pointer (0= none), counter countm, hash countk, and inserted-item countn.#[repr(C)],u64fields only — fixed-size, non-generic. - BoxOn
Disk - The on-disk image of a
BStackBox<T>: the standardBlockHeaderfollowed by the boxed value.#[repr(C, packed)](like every generatedXOnDisk) so there is no padding between the header andvalue— a requirement for the hand-writtenPodimpl and for reading the whole image back withbytemuck. - Construct
Error - The error a generated
newconstructor returns when a fallible construction step fails after it has already consumed the caller’s owned/strong/embedded children. - Deque
Iter - A front-to-back iterator over a
BStackDeque, yieldingio::Result<T>value handles. Created byBStackDeque::iter. - Deque
OnDisk - The on-disk image of a
BStackDeque: the block header, a pointer to the ring data block (0= none), its capacity in slots, and the circularhead/len.#[repr(C)]with onlyu64fields after the header, so it is padding-free and non-generic — the same layout for every element type. - EightCC
- An 8-byte type tag stored in every
BlockHeader. - Foreign
- A typed cross-file pointer to a
Tblock in anotherbstackfile — the self-qualifying counterpart ofBStackRef(an in-file offset with no file identity); see the module docs for its on-disk wire form. - Foreign
Host Allocator - An allocator adapter over a live foreign host — the bridge that lets the
crate’s entirely generic teardown / clone machinery (
OwnedRef,StrongRef,WeakRef,dealloc_range,__bstack_drop_children, …), all written againstA: BStackRaiiAllocator, run against another file without duplicating any of it. AForeign<T>field’s teardown resolves the target file’s host through the registry, wraps it here, and runs the sameTteardown it would run locally — every read/write lands in the foreign file (viastack), and every free is tagged with the foreign [FileId] so the home file’s WAL reclaims it there. - Foreign
Owned - The RAII dual of
BStackOwnedfor a target owned through aForeignpointer.bstack_dropdeep-frees the target in its own file;into_foreignrelinquishes ownership to re-store it. - Foreign
Rc - The RAII dual of
BStackRcfor a strong reference held through aForeignpointer.bstack_dropdecrements the target’s strong count in its own file (freeing at zero). - Foreign
Weak - The RAII dual of
BStackWeakfor a weak reference held through aForeignpointer (it stores the target’s control offset).bstack_dropdecrements the weak count in its own file. - Free
Many Error - The error a partial
free_manyreturns: the first underlying failure, plus every range whose free did not cleanly complete. - Hash
MapIter - An unordered iterator over a
BStackHashMap’s live entries, yieldingio::Result<(K, V)>. Created byBStackHashMap::iter; scans the buckets. - Hash
SetIter - An unordered iterator over a
BStackHashSet’s keys, yieldingio::Result<K>. Created byBStackHashSet::iter; scans the buckets. - Hash
SetOn Disk - The on-disk image of a
BStackHashSet: header, bucket-block pointer, bucket countcap, key countlen,used(occupied + tombstone), and the embedded Bloom filter’s handle offset.#[repr(C)],u64fields only. - Heap
OnDisk - The on-disk image of a
BStackBinaryHeap: header, array-block pointer (0= none), capacity in slots, and element count. Non-generic. - Into
Local Error - The error
ForeignOwned::into_local/ForeignRc::into_local/ForeignWeak::into_localreturns. - List
Iter - A front-to-back iterator over a
BStackLinkedList, yieldingio::Result<T>value handles. Created byBStackLinkedList::iter; walks thenextlinks. - List
OnDisk - The on-disk image of a
BStackLinkedList: the block header followed by thehead/tailnode offsets (0= empty) and the element count.#[repr(C)]with onlyu64fields after a 16-byte header, so it is naturally padding-free and non-generic — the same layout for every element type. - MapOn
Disk - The on-disk image of a
BStackHashMap: header, bucket-block pointer (0= none), bucket countcap, live-entry countlen, andused(occupied + tombstone).#[repr(C)], onlyu64fields after the header — non-generic. - Node
OnDisk - The on-disk image of one list node: the block header followed by the
prev/nextnode offsets (0= none) and a singleu64reference to the value block. Non-generic: the same layout for every element type. - NonNull
Offset - An
Offsetstatically guaranteed non-null — a resolved, real target address (a control-block back-pointer, a live child, a refcount counter). Carries the not-null invariant in the type, so a consumer that needs a genuine target takes aNonNullOffsetand the null check happens once, at the boundary, viaOffset::to_non_null— not re-checked at every deref. - Occupied
Entry - An occupied
Entry. - Offset
- A byte address into a bstack file’s stack — the target half of a wide pointer, and the currency of every on-disk read/write.
- Owned
Ref #[bstack_owned]: an exclusively-owned child — the without-allocator drop core a generated__bstack_drop_childrenmints for an owned field.- Replace
Error - The error a
#[bstack_mut]replace_<field>mutator returns when the swap fails partway through. - Small
String Map - An insertion-ordered map from
Stringkeys toT, backed by aVecof pairs. See the module docs. - String
OnDisk - The on-disk image of a
BStackString: header, a pointer to the UTF-8 bytes block (0= empty), and the byte length.#[repr(C)],u64fields only — fixed-size and non-generic, so the handle is a normal block. - Strong
Ref #[bstack_strong]on a plain(rc)T: holds just the data ref; teardown decrements the inline refcount and frees at zero.- Strong
Weak Ref #[bstack_strong]on an(rc, weak)T: holds the data ref and the control ref; teardown runs the two-phase strong-then-weak release. NotCopy— one strong-count debt, paid once.- Tree
OnDisk - The on-disk image of a
BStackBTreeMap: header, root node pointer (0= empty), and entry count. Non-generic. - Tree
SetOn Disk - The on-disk image of a
BStackBTreeSet: header, root node pointer (0= empty), key count, and the embedded Bloom filter’s handle offset. - Vacant
Entry - A vacant
Entry, holding the key it would insert under. - VecDesc
- The inline, fixed-size descriptor of a persistent vector: the current offset and byte size of its (reallocating) data block.
- WeakRef
#[bstack_weak]on an(rc, weak)T: holds only the control ref; teardown decrementsctrl.weakand frees the control block at zero. The data block is never touched. NotCopy— one weak-count debt, paid once.- WidePtr
- The crate’s wide pointer (a “fat pointer”): a persisted cross-file reference,
assembled from its three orthogonal components — a [
FileId] (which file), aTypeId(which type, or untyped), and anOffset(where in that file).
Enums§
- BStack
Cow - Clone-on-write ownership of a block of type
T. - Cast
Error - The error a fallible downcast (
BStackCastInto::cast_into) returns. It always hands the input slice back so an ownership-carryingBStackOwnedSliceis never dropped (and thus leaked) on a failed cast — the same hand-back contract as the crate’s other consuming operations (ReplaceError/ConstructError). - Entry
- A view into a single entry of a
SmallStringMap, present or not — the return ofSmallStringMap::entry.
Constants§
- STD_
WAL_ ANCHOR - Anchor offset for the bstack-provided freeing allocators: the second
u64word of the user-reserved region every one of them keeps at payload offset 0 and never hands out (FirstFit reserves 16 B there, GhostTree 32 B, Slab and CheckedSlab 24 B — all ≥ 16). Payload offset 0 is left asbstack_raii’s null niche, so the anchor is the next word,[8, 16).
Traits§
- BStack
Allocator - A trait for types that own a
BStackand manage contiguous byte regions within its payload. - BStack
Block - A typed handle over a block: a newtype around a
BStackRangethat knows its on-disk representation and how to be recursively freed. - BStack
Cast - The downcast discriminant. The returned
EightCCmust match the tag in a block’scrate::BlockHeaderfor a safe downcast to succeed. - BStack
Cast As - Downcast a borrowed slice to a typed handle by checking the block tag.
- BStack
Cast Into - Downcast an owned slice to a typed (bare) owned handle by checking the block
tag. The result carries no allocator; free it with
owned.bstack_drop(alloc)or wrap it viaowned.auto(alloc). - BStack
Drop - The safe teardown protocol for an affine (non-
Copy) owning handle: consumeselfand free the on-disk block(s) it owns. - BStack
Move - The per-block field destructure behind
bstack_move!: read every field, then free only the parent shell (the children stay live on disk). Ownership is transferred out — owned children asBStackOwned, strong asBStackRc, weak asOption<BStackWeak>, refs asBStackRef, POD by value. - BStack
Move Expr - The
bstack_move!entry point, dispatched on the wrapper handle type. - BStack
Owned Slice Allocator - Convenience supertrait for the common case of a
BStackAllocatorwhose handle type isBStackOwnedSliceand whose error type isio::Error. - BStack
Raii Allocator - The allocator every
bstack_raiioperation is bound on: aBStackOwnedSliceAllocatorthe layer can soundly build owning handles on top of. It is the crate-wide allocator capability — constructors,try_clone_in,bstack_drop, and every stdlib collection require it. - BStack
Shared - Implemented by refcounted blocks (
#[bstack_block(rc)]and#[bstack_block(rc, weak)]), i.e. any block that can be the target of a#[bstack_strong]field. - BStack
Weakable - Implemented only for blocks declared
#[bstack_block(rc, weak)]. - Hand
Back - The common surface of a hand-back error: it wraps an underlying
io::Error. - Pod
- Marker trait for “plain old data”.
- TryClone
- Duplicate
self, performing any fallible I/O the duplication requires, without needing an allocator. - TryClone
In - Deep-clone a whole block into a fresh, independent
BStackOwnedcopy, allocating the copy with the supplied allocator. - Zeroable
- Trait for types that can be safely created with
zeroed.
Functions§
- dealloc_
range ⚠ - Free a raw block range by reconstructing an owned slice and delegating to the
allocator. The central sink the generated
bstack_dropcode funnels through, since ranges carry no allocator of their own — a thin public entry over the sink-awareSink::dealloc(kept a free function because generatedbstack_dropcode and every collection call it by this name). - finish
- Complete a crash-left transaction in the allocator’s WAL block: reclaim the
slices its outcome orphaned and mark the persistent block idle. Returns the
number of slices reclaimed. This is what a caller runs once after
open— a completion, not a leaky recovery. Acquires the file’s WAL lock. An allocator that opts out of reclamation (wal_anchorisNone) has no WAL to complete, so this is a no-op returning0. - get_u64
- Read a little-endian
u64from the first 8 bytes ofbuf. - wal_
teardown - Tear down
handle(a whole owned subtree) as one crash-atomic batch of frees, so a crash mid-teardown is completed — not leaked — byfinishon the next open. This is whatBStackOwned::bstack_dropruns, so every owned teardown is automatically WAL-backed when the allocator names an anchor (BStackRaiiAllocator::wal_anchorreturnsSome); an allocator that returnsNonefalls straight through to a plainBStackDrop::bstack_dropand behaves exactly as before (mid-teardown crash ⇒ orphan leak).
Attribute Macros§
- bstack_
block #[bstack_block]— generate the on-disk layout and typed handle machinery.- bstack_
class #[bstack_class]— a#[bstack_block]that also persists RTTI.- bstack_
enum #[bstack_enum]— a tagged-union block.