bstack_raii 0.1.0

Typed, RAII-style ownership and lifetime layer over the bstack allocation primitives
Documentation
//! # `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`](BStackRaiiAllocator::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::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 without `mmap`.
//! * The whole layer speaks [`std::io::Result`] / [`std::io::Error`], a
//!   consequence of binding allocators to [`bstack::BStackOwnedSliceAllocator`]
//!   (which pins `Error = io::Error` and `Allocated<'a> = BStackOwnedSlice`).
//!
//! ## Status
//!
//! Feature-complete: the runtime primitives, the procedural macros
//! ([`macro@bstack_block`], [`macro@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.

// Lets code generated by `#[bstack_block]` reference this crate as
// `::bstack_raii::…` even from within the crate's own tests.
extern crate self as bstack_raii;

mod handback;
mod io_core;
mod primitives;
/// Runtime Type Information: a persisted, self-describing schema stack for
/// interpreting `bstack_raii` structures on disk with no compiled-in types.
pub mod rtti;
mod stdlib;
mod types;
mod util;

#[cfg(test)]
mod tests;

pub use handback::{CastError, ConstructError, HandBack, IntoLocalError, ReplaceError};
/// Codegen plumbing, re-exported for `#[bstack_block]`-generated code only. It is
/// named in [`BStackBlock`]'s (hidden) trait-method signatures, so the type must
/// stay `pub`; the supported way to clone is [`TryClone`] / [`TryCloneIn`].
#[doc(hidden)]
pub use io_core::ClonePlan;
pub use io_core::TryCloneIn;
/// The inert on-disk **wire** form of a [`Foreign`] pointer — the composed
/// wide pointer. Not part of the public API — generated
/// `#[bstack_block]` code names it through `::bstack_raii::WidePtr`; user code should
/// never use it directly.
#[doc(hidden)]
pub use io_core::registry;
pub use io_core::{
    ForeignHostAllocator, FreeManyError, STD_WAL_ANCHOR, dealloc_range, finish, wal_teardown,
};
/// Checked field-offset arithmetic for generated accessors — `mod primitives` is
/// private, so this doc-hidden crate-root alias gives `#[bstack_block]`-generated code a
/// stable path (`checked_field_offset`) without exposing the whole module. A base read
/// from an on-disk pointer can be corrupt/forged, so a bare `+` could panic under
/// `overflow-checks` or silently wrap; this errors instead.
#[doc(hidden)]
pub use primitives::checked_off as checked_field_offset;
pub use primitives::{EightCC, NonNullOffset, Offset, TryClone, WidePtr};
pub use stdlib::{
    BStackBTreeMap, BStackBTreeSet, BStackBinaryHeap, BStackBox, BStackCountingBloomFilter,
    BStackCow, BStackDeque, BStackHashMap, BStackHashSet, BStackLinkedList, BStackString,
    BTreeMapIter, BTreeSetIter, BloomOnDisk, BoxOnDisk, DequeIter, DequeOnDisk, HashMapIter,
    HashSetIter, HashSetOnDisk, HeapOnDisk, ListIter, ListOnDisk, MapOnDisk, NodeOnDisk,
    StringOnDisk, TreeOnDisk, TreeSetOnDisk,
};
pub use types::alloc::BStackRaiiAllocator;
pub use types::compiled::{
    BStackBlockVec, BStackOwned, BStackRc, BStackRefVec, BStackStrongVec, BStackVec, BStackWeak,
    BStackWeakVec, BlockHeader, ForeignOwned, ForeignRc, ForeignWeak, OwnedRef, StrongRef,
    StrongWeakRef, VecDesc, WeakRef,
};
pub use types::traits::{
    AutoDrop, BStackBlock, BStackCast, BStackCastAs, BStackCastInto, BStackDrop, BStackMove,
    BStackMoveExpr, BStackRef, BStackShared, BStackWeakable, Foreign,
};
pub use util::{Entry, OccupiedEntry, SmallStringMap, VacantEntry, get_u64};

// Re-exports for use by `#[bstack_block]`-generated code (and callers), so that
// generated code can name everything through `::bstack_raii::…` and downstream
// crates need not depend on `bstack` or `bytemuck` directly.
pub use bstack::{BStack, BStackAllocator, BStackOwnedSliceAllocator, BStackRange, BStackSlice};
pub use bytemuck::{Pod, Zeroable};

// Re-exported whole so generated code can call `::bstack_raii::bytemuck::bytes_of`.
pub use bytemuck;

// Procedural macros, re-exported so downstream depends only on `bstack_raii`.
pub use bstack_raii_derive::{bstack_block, bstack_cast, bstack_class, bstack_enum, bstack_move};

/// The `#[embed]` marker trait, named by `#[bstack_block]` / `#[bstack_enum]`-generated
/// bounds through `::bstack_raii::__private::BStackEmbeddable`. Not part of the public
/// API. (Every other codegen dependency now resolves through a public path — the
/// [`registry`] / [`rtti`] modules, the crate-root `checked_field_offset` alias, or a
/// capability-trait method like [`BStackWeakable::build_control_payload`] — so this
/// module holds only the marker.)
#[doc(hidden)]
pub mod __private {
    // A macro-only marker: `#[embed]` targets must be plain, self-contained blocks.
    // Only `#[bstack_block]`/`#[bstack_enum]`-generated code (and the stdlib) implement
    // it; no downstream code names it, so it lives here rather than in the prelude — the
    // `on_unimplemented` message fires regardless of visibility.
    pub use crate::types::traits::BStackEmbeddable;
}