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
//! [`ConstructError<F>`]: the error a generated `new` constructor returns when it
//! fails after consuming the caller's children.
use ;
use impl_source_error;
/// The error a generated `new` constructor returns when a fallible construction
/// step fails after it has already consumed the caller's owned/strong/embedded
/// children.
///
/// A generated `new` **consumes** the child handles you hand it (`#[bstack_owned]`,
/// `#[bstack_strong]`, `#[embed]`). A bare `io::Result` would then *lose* those
/// children on an allocation or write failure: their on-disk blocks would be
/// neither linked into the new block, freed, nor returned — an unreachable orphan
/// whose contents (an arbitrarily large subtree the caller just built) are
/// **unrecoverable**. So a failed `new` returns this instead,
/// handing the still-valid children back in [`fields`](Self::fields) — the same
/// region-hand-back contract as bstack's `BStackAllocError`,
/// [`BStackRaiiAllocError`](crate::registry::BStackRaiiAllocError), and
/// [`ReplaceError`](crate::ReplaceError).
///
/// `F` is the block's [`Fields`](crate::BStackMove::Fields) tuple — exactly
/// what `bstack_move!` hands back — so a recovered construction returns the
/// children in the same shape a later move would.
///
/// Only constructors that actually consume an owning child return this; a
/// constructor whose fields are all POD / `#[bstack_ref]` (nothing to orphan)
/// keeps a plain `io::Result`. There is deliberately **no**
/// `From<ConstructError> for io::Error`: propagating one with `?` would drop the
/// recovered children and silently re-orphan them, reintroducing the very defect
/// this type exists to prevent. Handle it explicitly, or `.unwrap()` it.
///
/// Implements [`std::error::Error`] (delegating [`Display`](fmt::Display) to
/// [`source`](Self::source)).
/// Propagate an inner `io::Error` as a `lost` construction (`fields: None`).
///
/// This is for the generated constructor's own `?` on the fallible *preparation*
/// steps — allocating a child vector's data block, re-encoding a `Foreign`, an
/// `#[embed]` copy — that run before (or between) the block's own allocation and
/// write. Those faults are rare mid-construction I/O errors; degrading them to
/// `lost` matches the pre-existing behaviour (the children a partial prep already
/// consumed were orphaned there too) while the *primary* allocation / write /
/// commit failures still hand the children back through
/// [`recovered`](ConstructError::recovered).
///
/// This affects only `?` **inside** a constructor (an `io::Error` becoming a
/// `ConstructError`); it deliberately does **not** provide the reverse
/// (`From<ConstructError> for io::Error`), so a caller cannot silently `?` a
/// failed `new` and re-orphan the returned children.
// Manual, so `F` need not be `Debug` (the handed-back handles generally aren't).
impl_source_error!;