error_stack/frame/
mod.rs

1mod frame_impl;
2mod kind;
3
4use alloc::boxed::Box;
5#[cfg(nightly)]
6use core::error;
7use core::{any::TypeId, error::Error, fmt};
8
9use self::frame_impl::FrameImpl;
10pub use self::kind::{AttachmentKind, FrameKind};
11
12/// A single context or attachment inside of a [`Report`].
13///
14/// `Frame`s are organized as a singly linked list, which can be iterated by calling
15/// [`Report::frames()`]. The head contains the current context or attachment, and the tail contains
16/// the root context created by [`Report::new()`]. The next `Frame` can be accessed by requesting it
17/// by calling [`Report::request_ref()`].
18///
19/// [`Report`]: crate::Report
20/// [`Report::frames()`]: crate::Report::frames
21/// [`Report::new()`]: crate::Report::new
22/// [`Report::request_ref()`]: crate::Report::request_ref
23pub struct Frame {
24    frame: Box<dyn FrameImpl>,
25    sources: Box<[Frame]>,
26}
27
28impl Frame {
29    /// Returns a shared reference to the source of this `Frame`.
30    ///
31    /// This corresponds to the `Frame` below this one in a [`Report`].
32    ///
33    /// [`Report`]: crate::Report
34    #[must_use]
35    pub const fn sources(&self) -> &[Self] {
36        &self.sources
37    }
38
39    /// Returns a mutable reference to the sources of this `Frame`.
40    ///
41    /// This corresponds to the `Frame` below this one in a [`Report`].
42    ///
43    /// [`Report`]: crate::Report
44    #[must_use]
45    pub fn sources_mut(&mut self) -> &mut [Self] {
46        &mut self.sources
47    }
48
49    /// Returns how the `Frame` was created.
50    #[must_use]
51    pub fn kind(&self) -> FrameKind<'_> {
52        self.frame.kind()
53    }
54
55    /// Requests the reference to `T` from the `Frame` if provided.
56    #[must_use]
57    #[cfg(nightly)]
58    pub fn request_ref<T>(&self) -> Option<&T>
59    where
60        T: ?Sized + 'static,
61    {
62        error::request_ref(self.as_error())
63    }
64
65    /// Requests the value of `T` from the `Frame` if provided.
66    #[must_use]
67    #[cfg(nightly)]
68    pub fn request_value<T>(&self) -> Option<T>
69    where
70        T: 'static,
71    {
72        error::request_value(self.as_error())
73    }
74
75    /// Returns if `T` is the held context or attachment by this frame.
76    #[must_use]
77    pub fn is<T: Send + Sync + 'static>(&self) -> bool {
78        self.frame.as_any().is::<T>()
79    }
80
81    /// Downcasts this frame if the held context or attachment is the same as `T`.
82    #[must_use]
83    pub fn downcast_ref<T: Send + Sync + 'static>(&self) -> Option<&T> {
84        self.frame.as_any().downcast_ref()
85    }
86
87    /// Downcasts this frame if the held context or attachment is the same as `T`.
88    #[must_use]
89    pub fn downcast_mut<T: Send + Sync + 'static>(&mut self) -> Option<&mut T> {
90        self.frame.as_any_mut().downcast_mut()
91    }
92
93    /// Returns the [`TypeId`] of the held context or attachment by this frame.
94    #[must_use]
95    pub fn type_id(&self) -> TypeId {
96        self.frame.as_any().type_id()
97    }
98
99    pub(crate) fn as_error(&self) -> &impl Error {
100        &self.frame
101    }
102}
103
104impl fmt::Debug for Frame {
105    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
106        let mut debug = fmt.debug_struct("Frame");
107
108        match self.kind() {
109            FrameKind::Context(context) => {
110                debug.field("context", &context);
111                debug.finish()
112            }
113            FrameKind::Attachment(AttachmentKind::Printable(attachment)) => {
114                debug.field("attachment", &attachment);
115                debug.finish()
116            }
117            FrameKind::Attachment(AttachmentKind::Opaque(_)) => debug.finish_non_exhaustive(),
118        }
119    }
120}
error_stack/frame/mod.rs

error_stack/frame/
mod.rs
