Expose Frames Iterator for the Backtrace Type

library/std/src/backtrace.rs

@@ -102,6 +102,7 @@ use crate::sync::atomic::{AtomicUsize, Ordering::SeqCst};
 use crate::sync::Mutex;
 use crate::sys_common::backtrace::{lock, output_filename};
 use crate::vec::Vec;
+use crate::marker::PhantomData;
 
 /// A captured OS thread stack backtrace.
 ///
@@ -146,23 +147,38 @@ fn _assert_send_sync() {
     _assert::<Backtrace>();
 }
 
-struct BacktraceFrame {
+/// A single frame of a backtrace.
+#[derive(Debug)]
+#[unstable(feature = "backtrace_frames", issue = "79676")]
+pub struct BacktraceFrame {
     frame: RawFrame,
     symbols: Vec<BacktraceSymbol>,
 }
 
+/// An iterator over the frames of a backtrace, created 
+/// by the [`frames`] method on [`Backtrace`].
+#[derive(Debug)]
+#[unstable(feature = "backtrace_frames", issue = "79676")]
+pub struct Frames<'a> {
+    inner: Vec<BacktraceFrame>,
+    _backtrace: PhantomData<&'a Backtrace>
+}
+
+#[derive(Debug, Clone)]
 enum RawFrame {
     Actual(backtrace_rs::Frame),
     #[cfg(test)]
     Fake,
 }
 
+#[derive(Clone)]
 struct BacktraceSymbol {
     name: Option<Vec<u8>>,
     filename: Option<BytesOrWide>,
     lineno: Option<u32>,
 }
 
+#[derive(Clone)]
 enum BytesOrWide {
     Bytes(Vec<u8>),
     Wide(Vec<u16>),
@@ -348,6 +364,25 @@ impl Backtrace {
     }
 }
 
+impl<'a> Backtrace {
+    /// Returns an iterator over the backtrace frames.
+    #[unstable(feature = "backtrace_frames", issue = "79676")]
+    pub fn frames(&self) -> Frames<'a> {
+        if let Inner::Captured(captured) = &self.inner {
+            let frames = &captured.lock().unwrap().frames;
+            Frames {
+                inner: frames.iter().map(|frame| frame.clone()).collect::<Vec<BacktraceFrame>>(),
+                _backtrace: PhantomData
+            }
+        } else {
+            Frames {
+                inner: vec![],
+                _backtrace: PhantomData
+            }
+        }
+    }
+}
+
 impl fmt::Display for Backtrace {
     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
         let mut capture = match &self.inner {
@@ -443,3 +478,33 @@ impl RawFrame {
         }
     }
 }
+
+#[unstable(feature = "backtrace_frames", issue = "79676")]
+impl<'a> AsRef<[BacktraceFrame]> for Frames<'a> {
+    fn as_ref(&self) -> &[BacktraceFrame] {
+        &self.inner
+    }
+}
+
+
+#[unstable(feature = "backtrace_frames", issue = "79676")]
+impl BacktraceFrame {
+    // Private clone method so that we don't expose a
+    // public BacktraceFrame.clone() by deriving Clone
+    fn clone(&self) -> Self {
+        BacktraceFrame {
+            frame: self.frame.clone(),
+            symbols: self.symbols.clone(),
+        }
+    }
+}
+
+#[unstable(feature = "backtrace_frames", issue = "79676")]
+impl<'a> Iterator for Frames<'a> {
+    type Item = BacktraceFrame;
+
+    fn next(&mut self) -> Option<BacktraceFrame> {
+        self.inner.pop()        
+    }
+}
+

library/std/src/backtrace/tests.rs

@@ -1,8 +1,7 @@
 use super::*;
 
-#[test]
-fn test_debug() {
-    let backtrace = Backtrace {
+fn generate_fake_backtrace() -> Backtrace {
+    Backtrace {
         inner: Inner::Captured(Mutex::new(Capture {
             actual_start: 1,
             resolved: true,
@@ -40,7 +39,12 @@ fn test_debug() {
                 },
             ],
         })),
-    };
+    }
+}
+
+#[test]
+fn test_debug() {
+    let backtrace = generate_fake_backtrace();
 
     #[rustfmt::skip]
     let expected = "Backtrace [\
@@ -51,3 +55,26 @@ fn test_debug() {
 
     assert_eq!(format!("{:#?}", backtrace), expected);
 }
+
+#[test]
+fn test_empty_frames_iterator() {
+    let empty_backtrace = Backtrace {
+        inner: Inner::Captured(Mutex::new(Capture {
+            actual_start: 1,
+            resolved: true,
+            frames: vec![],
+        }))
+    };
+
+    let iter = empty_backtrace.frames(); 
+
+    assert_eq!(iter.count(), 0);
+}
+
+#[test]
+fn test_frames_iterator() {
+    let backtrace = generate_fake_backtrace();
+    let iter = backtrace.frames();
+
+    assert_eq!(iter.count(), 3);
+}