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
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
//! Procedural macros for [`bstack_raii`](https://github.com/williamwutq/bstack_raii).
//!
//! Three entry points:
//!
//! * [`macro@bstack_block`] — attribute macro. Turns an ergonomic struct into a
//! parallel `#[repr(C, packed)]` on-disk representation plus generated
//! accessors, `BStackDrop`, `BStackCast`, and (for `(rc, weak)`)
//! `BStackWeakable` impls.
//! * [`bstack_move`] — function-like macro. Destructures a `BStackOwned<X>`,
//! transferring ownership of every field out as a tuple of typed handles.
//! * [`bstack_cast`] — function-like macro. Direction-inferring typed/untyped
//! handle conversion.
use TokenStream;
/// Build a directed "wrong item kind" error when a struct-only / enum-only attribute
/// macro is applied to the other item kind (or a union), instead of leaking rustc's
/// bare `expected `struct`` parse error. For genuinely malformed input (not any
/// recognizable item) it falls back to the real span-accurate parse error.
///
/// `wants_struct` is `true` for `#[bstack_block]` (wants a struct), `false` for
/// `#[bstack_enum]` (wants an enum). `code` is the `BSTACKxxxx` number.
/// `#[bstack_block]` — generate the on-disk layout and typed handle machinery.
///
/// # Arguments
///
/// `#[bstack_block(rc)]` / `#[bstack_block(rc, weak)]` select the refcount mode.
/// `tag = "…"` / `ctrl_tag = "…"` override the generated tags (see below).
/// `allow(overlong_tag)` / `allow(coerced_ref)` silence the corresponding
/// warnings (and a real `#[allow(deprecated)]` on the struct silences both,
/// since the warnings use the deprecation mechanism). All are optional and may
/// appear in any order.
///
/// # Generated items (for `struct X { .. }`)
///
/// * `struct X(BStackRange)` — the typed handle, and `struct XOnDisk`
/// (`#[repr(C, packed)]`, `Pod`) — the on-disk payload. `#[bstack_owned]` /
/// `#[bstack_strong]` / `#[bstack_weak]` / `#[bstack_ref]` fields lower to a
/// `u64` offset; un-annotated fields are stored inline (and must be `Pod`).
/// Wrapping a reference field in `Option<T>` makes it nullable (`0 == None`).
/// `(rc)` injects an inline `refcount`; `(rc, weak)` injects a `ctrl`
/// back-pointer and emits an `XOnDiskRef` control block.
/// * `impl BStackCast / BStackBlock / BStackDrop`, plus `BStackShared`
/// (`rc` / `rc, weak`), `BStackWeakable` (`rc, weak`), and `BStackMove`
/// (plain blocks — the `bstack_move!` target).
/// * Field accessors, `set_<field>` for weak fields, and a `new` constructor.
///
/// # EightCC tag generation
///
/// Each block's [`EightCC`](../bstack_raii/struct.EightCC.html) is an 8-byte tag
/// = a **readable ASCII prefix** over the first bytes, followed by the tail of a
/// **64-bit FNV-1a hash** of `crate_name ++ "\0" ++ type_name` (little-endian),
/// with the type's `module_path!()` folded into the tail so two same-named types
/// in different modules of one crate stay distinct. Every hash-tail byte has its
/// high bit set, so it lands in the non-printable range and reads as
/// clearly-not-a-name in a hex dump. The hash keeps distinct types apart even
/// when their prefixes collide, and is deterministic (stable across
/// builds/versions) so it is safe as on-disk ABI.
///
/// The prefix is derived from the type name: initials of the camel-case words
/// (≥ 2 words), or the de-voweled single word, clamped to 2–4 bytes. Override it
/// with `tag = "PREFIX"` (0–8 bytes; fewer than 8 leaves room for hash, exactly
/// 8 is a fully manual tag, over 8 warns and truncates). The control block's tag
/// keeps the **same** readable prefix as the data tag, distinguished by a toggled
/// reserved hash bit (`EightCC::with_ctrl_bit` — structurally distinct regardless
/// of the prefix), or is an explicit `ctrl_tag`.
/// `#[bstack_enum]` — a tagged-union block.
///
/// Lowers an `enum` to a fixed-size block: a discriminant plus a payload area
/// sized to the largest variant. A variant is either:
///
/// * a **POD aggregate** — unit (`V`), an all-`Pod` tuple (`V(A, B, ..)`), or an
/// all-`Pod` struct (`V { x: A, .. }`); the fields are packed into the payload
/// in declaration order (read/written unaligned, so alignment is irrelevant),
/// with no ownership annotation; or
/// * an **annotated single-field tuple** `#[bstack_owned]` / `#[bstack_strong]` /
/// `#[bstack_weak]` / `#[bstack_ref]` `V(T)` — a `u64` offset to the child /
/// control block, released on teardown per the annotation.
///
/// All three modes are supported (`#[bstack_enum]`, `(rc)`, `(rc, weak)`).
/// Duplicate discriminant values are rejected (rustc's `E0081` cannot fire, since
/// the macro replaces the `enum`).
///
/// # Arguments
///
/// Accepts the same `rc` / `weak` / `tag = "…"` / `ctrl_tag = "…"` /
/// `allow(overlong_tag)` as [`macro@bstack_block`], plus **`repr(..)`** to fix
/// the discriminant width: `repr(u8|u16|u32|u64|i8|i16|i32|i64)`, or
/// `repr(aligned)` (== `repr(u64)`, so the 8-byte discriminant leaves the payload
/// 8-aligned and its on-disk refs get aligned writes). `usize` / `isize` are
/// rejected (bstack offsets are 64-bit). Without `repr`, the width is **inferred**
/// as the smallest integer type holding every variant's discriminant — honoring
/// explicit `= value` discriminants (Rust's rules: explicit, else previous + 1)
/// and choosing a **signed** type if any value is negative.
///
/// Generates:
/// * `struct E(BStackRange)` (the handle) and its `EOnDisk` payload.
/// * `enum EData` — the in-memory owned form: passed to `new` **and** returned by
/// `bstack_move!` (construction and destructuring are duals), and `enum EView`
/// — the read result (POD by value, owned/ref children as borrowed handles, a
/// weak variant upgraded to `Option<BStackRc>`).
/// * `impl BStackCast / BStackBlock / BStackDrop / BStackMove`, plus
/// `E::new(alloc, EData)`, `E::read(alloc) -> EView`, and `E::as_slice`.
/// `bstack_move!` and `bstack_cast!` work on enums as on structs.
///
/// An enum is always **referenced** (it is a block; store it as a field of a
/// struct — inline embedding is not supported).
/// `#[bstack_class]` — a `#[bstack_block]` that also persists RTTI.
///
/// A **drop-in replacement** for [`macro@bstack_block]` (on a struct): it emits
/// the identical block machinery (handle, `XOnDisk`, accessors, teardown, clone,
/// `new`) **and** a self-describing schema. The macro registers a descriptor
/// builder into `bstack_raii::rtti::RTTI_TYPES` (via `linkme`, at link time), and
/// `bstack_raii::rtti::sync(file)` walks that set to persist every compiled-in
/// type's schema — letting a general program read the type's structures off disk
/// with no compiled-in Rust types.
///
/// Accepts the same arguments as [`macro@bstack_block]` (`rc` / `rc, weak` /
/// `tag = "…"` / `ctrl_tag = "…"` / `allow(…)`). Not yet supported (a clear
/// compile error, never a partial schema): `#[bstack_class]` on an `enum`, generic
/// blocks, `Foreign` fields, tuple fields, and `#[bstack_static]` class variables.
/// `bstack_move!(handle)` / `bstack_move!(owned, allocator)` — transfer every
/// field out of a block, freeing only the parent shell.
///
/// Reads each field's `BStackRef`/POD value from `XOnDisk` (capturing `ctrl`
/// refs for `(rc, weak)` / weak fields first), `dealloc_range`s the parent shell
/// only, then reconstructs typed handles and returns them as a
/// `Result<(..), io::Error>` tuple. Two forms select where the allocator comes
/// from:
///
/// * `bstack_move!(handle)` — for an allocator-carrying handle: a `BStackRc<X>`
/// (a `try_unwrap`, sole-owner only) or an `AutoDrop`-wrapped owned handle.
/// Dispatched through [`BStackMoveExpr`], inferring the impl from the type.
/// * `bstack_move!(owned, allocator)` — for a **bare** `BStackOwned<X>`, which
/// carries no allocator; the allocator is supplied explicitly (symmetric with
/// `owned.bstack_drop(allocator)`).
/// `bstack_cast!(expr as Target)` — type-checked handle conversion. The target
/// is given explicitly (a function-like macro can't read a `let` annotation) and
/// selects the direction:
///
/// * `owned as BStackOwnedSlice` — owned upcast (infallible).
/// * `slice as BStackOwned<X, _>` — owned downcast → `io::Result<Result<BStackOwned<X>, _>>`.
/// * `slice as X` — borrowed downcast off a `BStackSlice` → `io::Result<Option<X>>`.
///
/// The borrowed upcast is the generated `handle.as_slice(stack)` method.