rootcause_internals/lib.rs
1#![no_std]
2#![forbid(
3 missing_docs,
4 elided_lifetimes_in_paths,
5 clippy::alloc_instead_of_core,
6 clippy::std_instead_of_alloc,
7 clippy::std_instead_of_core,
8 clippy::missing_safety_doc,
9 clippy::missing_docs_in_private_items,
10 clippy::undocumented_unsafe_blocks,
11 clippy::multiple_unsafe_ops_per_block,
12 clippy::as_ptr_cast_mut,
13 clippy::ptr_as_ptr,
14 rustdoc::invalid_rust_codeblocks,
15 rustdoc::broken_intra_doc_links,
16 missing_copy_implementations,
17 unused_doc_comments
18)]
19#![allow(rustdoc::private_intra_doc_links)]
20//! Internal implementation crate for [`rootcause`].
21//!
22//! # Overview
23//!
24//! This crate contains the low-level, type-erased data structures and unsafe
25//! operations that power the [`rootcause`] error reporting library. It provides
26//! the foundation for zero-cost type erasure through vtable-based dispatch.
27//!
28//! **This crate is an implementation detail.** No semantic versioning
29//! guarantees are provided. Users should depend on the [`rootcause`] crate, not
30//! this one.
31//!
32//! # Architecture
33//!
34//! The crate is organized around two parallel type hierarchies for attachments
35//! and reports:
36//!
37//! - **[`attachment`]**: Type-erased attachment storage
38//! - [`RawAttachment`]: Owned attachment with [`Box`]-based allocation
39//! - [`RawAttachmentRef`]/[`RawAttachmentMut`]: Borrowed reference to an
40//! attachment (shared/mutable)
41//! - [`AttachmentData`]: `#[repr(C)]` wrapper enabling field access on erased
42//! types
43//! - [`AttachmentVtable`]: Function pointers for type-erased dispatch
44//!
45//! - **[`report`]**: Type-erased report storage (similar structure)
46//! - [`RawReport`]: Owned report with [`Arc`]-based allocation
47//! - [`RawReportRef`]/[`RawReportMut`]: Borrowed references (shared/mutable)
48//! - [`ReportData`]: `#[repr(C)]` wrapper for field access
49//! - [`ReportVtable`]: Function pointers for dispatch
50//!
51//! - **[`handlers`]**: Trait definitions for formatting and behavior
52//! - [`ContextHandler`]: Defines how error contexts are formatted
53//! - [`AttachmentHandler`]: Defines how attachments are formatted
54//!
55//! # Safety Strategy
56//!
57//! Type erasure requires careful handling to maintain Rust's type safety
58//! guarantees. When we erase a type like `AttachmentData<MyError>` to
59//! `AttachmentData<Erased>`, we must ensure that the vtable function pointers
60//! still match the actual concrete type stored in memory.
61//!
62//! This crate maintains safety through:
63//!
64//! - **Module-based encapsulation**: Safety-critical types keep fields
65//! module-private, making invariants locally verifiable within a single file
66//! - **`#[repr(C)]` layout**: Enables safe field projection on type-erased
67//! pointers without constructing invalid references
68//! - **Documented vtable contracts**: Each vtable method specifies exactly when
69//! it can be safely called
70//!
71//! See the individual module documentation ([`attachment`], [`report`]) for
72//! detailed explanations of how these patterns are applied.
73//!
74//! [`rootcause`]: https://docs.rs/rootcause/latest/rootcause/
75//! [`AttachmentData`]: attachment::data::AttachmentData
76//! [`AttachmentVtable`]: attachment::vtable::AttachmentVtable
77//! [`ReportData`]: report::data::ReportData
78//! [`ReportVtable`]: report::vtable::ReportVtable
79//! [`ContextHandler`]: handlers::ContextHandler
80//! [`AttachmentHandler`]: handlers::AttachmentHandler
81//! [`Box`]: alloc::boxed::Box
82//! [`Arc`]: triomphe::Arc
83
84extern crate alloc;
85
86mod attachment;
87pub mod handlers;
88mod report;
89mod util;
90
91pub use attachment::{RawAttachment, RawAttachmentMut, RawAttachmentRef};
92pub use report::{RawReport, RawReportMut, RawReportRef};