1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
//! # `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;
/// Runtime Type Information: a persisted, self-describing schema stack for
/// interpreting `bstack_raii` structures on disk with no compiled-in types.
pub use ;
/// 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`].
pub use ClonePlan;
pub use 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.
pub use registry;
pub use ;
/// 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.
pub use checked_off as checked_field_offset;
pub use ;
pub use ;
pub use BStackRaiiAllocator;
pub use ;
pub use ;
pub use ;
// 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 ;
pub use ;
// 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 ;
/// 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.)