//! 支持捕获 OS 线程的栈回溯
//!
//! 该模块包含从 OS 线程本身捕获正在运行的 OS 线程的栈回溯所必需的支持。
//! `Backtrace` 类型支持通过 `Backtrace::capture` 和 `Backtrace::force_capture` 函数捕获栈跟踪。
//!
//! 回溯通常很容易附加到错误 (例如，实现 `std::error::Error` 的类型) 上，以获取产生错误的因果关系。
//!
//! ## Accuracy
//!
//! 回溯试图尽可能地准确，但不保证回溯的准确度。
//! 报告时，指令指针，符号名称，文件名，行号等可能都不正确。
//! 我们会尽最大努力尝试准确性，但是，始终欢迎任何错误报告指出改进的领域!
//!
//! 对于大多数平台，带有 filename/line 编号的回溯要求使用调试信息编译程序。没有调试信息，将不会报告 filenames/line 号。
//!
//! ## 平台支持
//!
//! 并非 std 编译的所有平台都支持捕获回溯。一些平台在捕获回溯时根本不执行任何操作。
//! 要检查平台是否支持捕获回溯，您可以参考 `Backtrace::status` 作为 `Backtrace::status` 的枚举。
//!
//! 像上面一样，准确性平台的支持是尽力而为的。
//! 有时库可能在运行时不可用，或者可能出现问题，从而导致无法捕获回溯。
//! 请随时报告平台无法捕获回溯的问题！
//!
//! ## 环境变量
//!
//! 默认情况下，`Backtrace::capture` 函数实际上可能不会捕获回溯。它的行为受两个环境变量控制：
//!
//! * `RUST_LIB_BACKTRACE` - 如果设置为 `0`，则 `Backtrace::capture` 将永远不会捕获回溯。任何其他值设置都将启用 `Backtrace::capture`。
//!
//! * `RUST_BACKTRACE` - 如果未设置 `RUST_LIB_BACKTRACE`，则使用与 `RUST_LIB_BACKTRACE` 相同的规则查询此变量。
//!
//! * 如果以上两个环境变量均未设置，则 `Backtrace::capture` 将被禁用。
//!
//! 捕获回溯可能是相当昂贵的运行时操作，因此环境变量允许强制禁用此运行时性能命中值，或者允许在某些程序中有选择地启用它。
//!
//! 注意，可以使用 `Backtrace::force_capture` 函数来忽略这些环境变量。
//! 另请注意，一旦创建第一个回溯，环境变量的状态就会被缓存，因此在运行时更改 `RUST_LIB_BACKTRACE` 或 `RUST_BACKTRACE` 可能实际上不会改变回溯的捕获方式。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![stable(feature = "backtrace", since = "1.65.0")]

#[cfg(test)]
mod tests;

// NB: 关于解决回溯的说明：
//
// 回溯主要发生在两个步骤中，一个是我们实际捕获栈回溯的位置，从而为我们提供了与栈帧相对应的指令指针列表。
// 接下来，我们使用这些指令指针，并将它们逐个转换为人类可读的名称 (例如 `main`)。
//
// 第一阶段可能会有些昂贵 (遍历栈)，尤其是在 MSVC 上，在该 MSVC 上，将参考调试信息以将内联帧返回为各自的帧。
// 但是，在咨询调试信息时，第二阶段几乎总是非常昂贵 (有时约数毫秒)。
//
// 我们试图通过尽可能长时间地将地址解析为人类可读的名称来尽可能摊销此费用。
// 当调用 `Backtrace::create` 捕获回溯时，它实际上并不执行任何符号解析，而是仅在需要打印符号之前才对它们进行延迟解析。
// 这样，我们可以使捕获回溯并将其扔掉便宜得多，但实际上打印回溯仍基本上是相同的成本。
//
// 这种策略是以 `Backtrace` 内部需要进行一些同步为代价的，但是相对于捕获回溯或实际对其进行符号化而言，这是一个相对较低的代价。
//
//
//
//
//
//
//
//
//
//
//

use crate::backtrace_rs::{self, BytesOrWideString};
use crate::cell::UnsafeCell;
use crate::env;
use crate::ffi::c_void;
use crate::fmt;
use crate::sync::atomic::{AtomicUsize, Ordering::Relaxed};
use crate::sync::Once;
use crate::sys_common::backtrace::{lock, output_filename};
use crate::vec::Vec;

/// 捕获的 OS 线程栈回溯。
///
/// 此类型表示在先前时间点捕获的 OS 线程的栈回溯。
/// 在某些情况下，由于配置，`Backtrace` 类型在内部可能为空。
/// 有关更多信息，请参见 `Backtrace::capture`。
///
#[stable(feature = "backtrace", since = "1.65.0")]
#[must_use]
pub struct Backtrace {
    inner: Inner,
}

/// 回溯的当前状态，指示它是否已捕获或由于其他原因而为空。
///
#[stable(feature = "backtrace", since = "1.65.0")]
#[non_exhaustive]
#[derive(Debug, PartialEq, Eq)]
pub enum BacktraceStatus {
    /// 不支持捕获回溯，这可能是因为当前平台尚未实现。
    ///
    #[stable(feature = "backtrace", since = "1.65.0")]
    Unsupported,
    /// 通过 `RUST_LIB_BACKTRACE` 或 `RUST_BACKTRACE` 环境变量已禁用捕获回溯。
    ///
    #[stable(feature = "backtrace", since = "1.65.0")]
    Disabled,
    /// 回溯已被捕获，并且 `Backtrace` 在呈现时应打印合理的信息。
    ///
    #[stable(feature = "backtrace", since = "1.65.0")]
    Captured,
}

enum Inner {
    Unsupported,
    Disabled,
    Captured(LazilyResolvedCapture),
}

struct Capture {
    actual_start: usize,
    resolved: bool,
    frames: Vec<BacktraceFrame>,
}

fn _assert_send_sync() {
    fn _assert<T: Send + Sync>() {}
    _assert::<Backtrace>();
}

/// 回溯的单个帧。
#[unstable(feature = "backtrace_frames", issue = "79676")]
pub struct BacktraceFrame {
    frame: RawFrame,
    symbols: Vec<BacktraceSymbol>,
}

#[derive(Debug)]
enum RawFrame {
    Actual(backtrace_rs::Frame),
    #[cfg(test)]
    Fake,
}

struct BacktraceSymbol {
    name: Option<Vec<u8>>,
    filename: Option<BytesOrWide>,
    lineno: Option<u32>,
    colno: Option<u32>,
}

enum BytesOrWide {
    Bytes(Vec<u8>),
    Wide(Vec<u16>),
}

#[stable(feature = "backtrace", since = "1.65.0")]
impl fmt::Debug for Backtrace {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        let capture = match &self.inner {
            Inner::Unsupported => return fmt.write_str("<unsupported>"),
            Inner::Disabled => return fmt.write_str("<disabled>"),
            Inner::Captured(c) => c.force(),
        };

        let frames = &capture.frames[capture.actual_start..];

        write!(fmt, "Backtrace ")?;

        let mut dbg = fmt.debug_list();

        for frame in frames {
            if frame.frame.ip().is_null() {
                continue;
            }

            dbg.entries(&frame.symbols);
        }

        dbg.finish()
    }
}

#[unstable(feature = "backtrace_frames", issue = "79676")]
impl fmt::Debug for BacktraceFrame {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut dbg = fmt.debug_list();
        dbg.entries(&self.symbols);
        dbg.finish()
    }
}

impl fmt::Debug for BacktraceSymbol {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        // FIXME: 改进格式: https://github.com/rust-lang/rust/issues/65280
        // FIXME: 另外，将列号包括在调试格式中，因为 Display 已经拥有了它们。
        // 在存在稳定的每帧访问器之前，不应更改格式：
        // https://github.com/rust-lang/rust/issues/65280#issuecomment-638966585
        write!(fmt, "{{ ")?;

        if let Some(fn_name) = self.name.as_ref().map(|b| backtrace_rs::SymbolName::new(b)) {
            write!(fmt, "fn: \"{:#}\"", fn_name)?;
        } else {
            write!(fmt, "fn: <unknown>")?;
        }

        if let Some(fname) = self.filename.as_ref() {
            write!(fmt, ", file: \"{:?}\"", fname)?;
        }

        if let Some(line) = self.lineno {
            write!(fmt, ", line: {:?}", line)?;
        }

        write!(fmt, " }}")
    }
}

impl fmt::Debug for BytesOrWide {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        output_filename(
            fmt,
            match self {
                BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
                BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
            },
            backtrace_rs::PrintFmt::Short,
            crate::env::current_dir().as_ref().ok(),
        )
    }
}

impl Backtrace {
    /// 返回是否通过环境变量启用回溯捕获。
    ///
    fn enabled() -> bool {
        // 高速缓存读取环境变量的结果以快速捕获回溯，因为否则每次读取环境变量都可能有些慢。
        //
        //
        static ENABLED: AtomicUsize = AtomicUsize::new(0);
        match ENABLED.load(Relaxed) {
            0 => {}
            1 => return false,
            _ => return true,
        }
        let enabled = match env::var("RUST_LIB_BACKTRACE") {
            Ok(s) => s != "0",
            Err(_) => match env::var("RUST_BACKTRACE") {
                Ok(s) => s != "0",
                Err(_) => false,
            },
        };
        ENABLED.store(enabled as usize + 1, Relaxed);
        enabled
    }

    /// 捕获当前线程的栈回溯。
    ///
    /// 此函数将捕获当前 OS 执行线程的栈回溯，并返回 `Backtrace` 类型，该类型以后可用于打印整个栈跟踪或将其呈现为字符串。
    ///
    /// 如果没有同时设置 `RUST_BACKTRACE` 或 `RUST_LIB_BACKTRACE` backtrace 变量，则此函数将为 noop。
    /// 如果设置并启用了任何一个环境变量，则此函数实际上将捕获回溯。
    /// 捕获回溯可能会占用大量内存并且速度很慢，因此这些环境变量允许自由使用 `Backtrace::capture`，并且仅在设置环境变量时才会导致速度降低。
    ///
    ///
    /// 要强制捕获回溯，而不管环境变量如何，请使用 `Backtrace::force_capture` 函数。
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "backtrace", since = "1.65.0")]
    #[inline(never)] // 要确保这里有一个框架要删除
    pub fn capture() -> Backtrace {
        if !Backtrace::enabled() {
            return Backtrace { inner: Inner::Disabled };
        }
        Backtrace::create(Backtrace::capture as usize)
    }

    /// 无论环境变量配置如何，都将强制捕获完整的回溯。
    ///
    /// 此函数的行为与 `capture` 相同，不同之处在于它忽略 `RUST_BACKTRACE` 和 `RUST_LIB_BACKTRACE` 环境变量的值，始终捕获回溯。
    ///
    ///
    /// 请注意，在某些平台上，捕获回溯可能是一项昂贵的操作，因此在对性能敏感的代码部分中应谨慎使用。
    ///
    ///
    ///
    ///
    #[stable(feature = "backtrace", since = "1.65.0")]
    #[inline(never)] // 要确保这里有一个框架要删除
    pub fn force_capture() -> Backtrace {
        Backtrace::create(Backtrace::force_capture as usize)
    }

    /// 无论环境变量配置如何，都将强制捕获禁用的回溯。
    ///
    #[stable(feature = "backtrace", since = "1.65.0")]
    #[rustc_const_stable(feature = "backtrace", since = "1.65.0")]
    pub const fn disabled() -> Backtrace {
        Backtrace { inner: Inner::Disabled }
    }

    // 捕获在 `ip` 寻址的函数之前开始的回溯
    //
    fn create(ip: usize) -> Backtrace {
        let _lock = lock();
        let mut frames = Vec::new();
        let mut actual_start = None;
        unsafe {
            backtrace_rs::trace_unsynchronized(|frame| {
                frames.push(BacktraceFrame {
                    frame: RawFrame::Actual(frame.clone()),
                    symbols: Vec::new(),
                });
                if frame.symbol_address().addr() == ip && actual_start.is_none() {
                    actual_start = Some(frames.len());
                }
                true
            });
        }

        // 如果没有框架出现，请假定这是不受支持的平台，因为 `backtrace` 目前尚无法提供学习该方法的平台，这应该是一个足够好的近似值。
        //
        //
        let inner = if frames.is_empty() {
            Inner::Unsupported
        } else {
            Inner::Captured(LazilyResolvedCapture::new(Capture {
                actual_start: actual_start.unwrap_or(0),
                frames,
                resolved: false,
            }))
        };

        Backtrace { inner }
    }

    /// 返回此回溯的状态，指示此回溯请求是否不受支持，已禁用或是否实际捕获了栈跟踪。
    ///
    ///
    #[stable(feature = "backtrace", since = "1.65.0")]
    #[must_use]
    pub fn status(&self) -> BacktraceStatus {
        match self.inner {
            Inner::Unsupported => BacktraceStatus::Unsupported,
            Inner::Disabled => BacktraceStatus::Disabled,
            Inner::Captured(_) => BacktraceStatus::Captured,
        }
    }
}

impl<'a> Backtrace {
    /// 返回回溯帧上的迭代器。
    #[must_use]
    #[unstable(feature = "backtrace_frames", issue = "79676")]
    pub fn frames(&'a self) -> &'a [BacktraceFrame] {
        if let Inner::Captured(c) = &self.inner { &c.force().frames } else { &[] }
    }
}

#[stable(feature = "backtrace", since = "1.65.0")]
impl fmt::Display for Backtrace {
    fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
        let capture = match &self.inner {
            Inner::Unsupported => return fmt.write_str("unsupported backtrace"),
            Inner::Disabled => return fmt.write_str("disabled backtrace"),
            Inner::Captured(c) => c.force(),
        };

        let full = fmt.alternate();
        let (frames, style) = if full {
            (&capture.frames[..], backtrace_rs::PrintFmt::Full)
        } else {
            (&capture.frames[capture.actual_start..], backtrace_rs::PrintFmt::Short)
        };

        // 在打印路径时，我们尝试剥离 cwd (如果存在)，否则我们仅按原样打印路径。
        // 请注意，我们也只对短格式执行此操作，因为如果已写满，则可能要打印所有内容。
        //
        //
        let cwd = crate::env::current_dir();
        let mut print_path = move |fmt: &mut fmt::Formatter<'_>, path: BytesOrWideString<'_>| {
            output_filename(fmt, path, style, cwd.as_ref().ok())
        };

        let mut f = backtrace_rs::BacktraceFmt::new(fmt, style, &mut print_path);
        f.add_context()?;
        for frame in frames {
            if frame.symbols.is_empty() {
                f.frame().print_raw(frame.frame.ip(), None, None, None)?;
            } else {
                for symbol in frame.symbols.iter() {
                    f.frame().print_raw_with_column(
                        frame.frame.ip(),
                        symbol.name.as_ref().map(|b| backtrace_rs::SymbolName::new(b)),
                        symbol.filename.as_ref().map(|b| match b {
                            BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
                            BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
                        }),
                        symbol.lineno,
                        symbol.colno,
                    )?;
                }
            }
        }
        f.finish()?;
        Ok(())
    }
}

struct LazilyResolvedCapture {
    sync: Once,
    capture: UnsafeCell<Capture>,
}

impl LazilyResolvedCapture {
    fn new(capture: Capture) -> Self {
        LazilyResolvedCapture { sync: Once::new(), capture: UnsafeCell::new(capture) }
    }

    fn force(&self) -> &Capture {
        self.sync.call_once(|| {
            // SAFETY: 此独家引用不能与任何其他 `Once` 重叠，以确保在此闭包返回之前，调用者将被阻止 `Once` 还保证只有一个调用者会进入此闭包
            //
            //
            unsafe { &mut *self.capture.get() }.resolve();
        });

        // SAFETY: 此共享的引用不能与上面的专有引用重叠
        unsafe { &*self.capture.get() }
    }
}

// SAFETY: 使用线程安全的 `Once` 同步访问内部值，只要 `Capture` 是 `Sync`，`LazilyResolvedCapture` 也是
//
unsafe impl Sync for LazilyResolvedCapture where Capture: Sync {}

impl Capture {
    fn resolve(&mut self) {
        // 如果我们已经解决了，那就什么都不用做！
        if self.resolved {
            return;
        }
        self.resolved = true;

        // 根据 `backtrace` crate 的要求，使用 Backtrace 锁进行同步，然后实际解决所有问题。
        //
        //
        let _lock = lock();
        for frame in self.frames.iter_mut() {
            let symbols = &mut frame.symbols;
            let frame = match &frame.frame {
                RawFrame::Actual(frame) => frame,
                #[cfg(test)]
                RawFrame::Fake => unimplemented!(),
            };
            unsafe {
                backtrace_rs::resolve_frame_unsynchronized(frame, |symbol| {
                    symbols.push(BacktraceSymbol {
                        name: symbol.name().map(|m| m.as_bytes().to_vec()),
                        filename: symbol.filename_raw().map(|b| match b {
                            BytesOrWideString::Bytes(b) => BytesOrWide::Bytes(b.to_owned()),
                            BytesOrWideString::Wide(b) => BytesOrWide::Wide(b.to_owned()),
                        }),
                        lineno: symbol.lineno(),
                        colno: symbol.colno(),
                    });
                });
            }
        }
    }
}

impl RawFrame {
    fn ip(&self) -> *mut c_void {
        match self {
            RawFrame::Actual(frame) => frame.ip(),
            #[cfg(test)]
            RawFrame::Fake => crate::ptr::invalid_mut(1),
        }
    }
}