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
//! The crate's **hand-back errors** — one home for the family and its shared
//! machinery.
//!
//! Several operations *consume* a resource (a moved-in child, a value to install,
//! a freshly resized region, a slice being downcast). When such an operation fails
//! partway, a bare `io::Error` would silently drop that resource — its on-disk
//! block neither linked nor returned, an unreachable orphan. So each such
//! operation returns a dedicated error that wraps the underlying [`io::Error`]
//! **and hands the resource back**.
//!
//! The concrete errors live here: [`ConstructError`] (a failed `new`),
//! [`ReplaceError`] (a failed `replace_<field>`), and [`CastError`] (a failed
//! `bstack_cast!`). Two more share this contract but live with their functional
//! siblings: [`BStackRaiiAllocError`](crate::registry::BStackRaiiAllocError) and
//! [`FreeManyError`](crate::FreeManyError).
//!
//! Every `source`-field error wraps an `io::Error` and delegates
//! [`Display`](std::fmt::Display) / [`Error`](std::error::Error) to it identically;
//! [`impl_source_error!`] emits that shared boilerplate (and the [`HandBack`] impl)
//! so each type only hand-writes what differs: its constructors, its
//! recovered-resource accessors, and its `Debug` (which masks the handed-back
//! resource, since the resource generally is not `Debug`). [`CastError`] is instead
//! a two-variant enum — a clean tag/size mismatch is *not* an I/O error — so it
//! hand-writes its impls and does not implement [`HandBack`].
use io;
pub use CastError;
pub use ConstructError;
pub use IntoLocalError;
pub use ReplaceError;
/// The common surface of a hand-back error: it wraps an underlying [`io::Error`].
///
/// The handed-back *resource* differs per type (a value, a child tuple, a range,
/// a slice), so it stays on the concrete type's own accessors; this trait is just
/// the shared "what went wrong" half.
/// Emit the `Display` / `Error` / [`HandBack`] impls shared by every hand-back
/// error whose underlying `io::Error` lives in a `source` field. `Debug` is left
/// to the type (it masks the non-`Debug` handed-back resource).
///
/// Usage: `impl_source_error!(BStackRaiiAllocError);` or, for a generic type,
/// `impl_source_error!(ReplaceError<V>);`.
}
};
}
pub use impl_source_error;