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
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
//! 支持捕获 OS 线程的栈回溯
//!
//! 该模块包含从 OS 线程本身捕获正在运行的 OS 线程的栈回溯所必需的支持。
//! `Backtrace` 类型支持通过 `Backtrace::capture` 和 `Backtrace::force_capture` 函数捕获栈跟踪。
//!
//! 回溯通常很容易附加到错误 (例如,实现 `std::error::Error` 的类型) 上,以获取产生错误的因果关系。
//!
//! > **Note**: 该模块是不稳定的,并且是在 [RFC 2504] 中设计的,因此您
//! > 可以在 [tracking issue] 中了解有关其状态的更多信息。
//!
//! [RFC 2504]: https://github.com/rust-lang/rfcs/blob/master/text/2504-fix-error.md
//! [tracking issue]: https://github.com/rust-lang/rust/issues/53487
//!
//! ## Accuracy
//!
//! 回溯试图尽可能地准确,但不保证回溯的准确度。
//! 报告时,指令指针,符号名称,文件名,行号等可能都不正确。
//! 尽力而为,力求做到准确,但是,始终欢迎欢迎带错误的地方指出改进的地方!
//!
//! 对于大多数平台,带有 filename/line 编号的回溯要求使用调试信息编译程序。没有调试信息,将不会报告 filenames/line 号。
//!
//! ## 平台支持
//!
//! 并非所有 libstd 编译的平台都支持捕获回溯。
//! 一些平台在捕获回溯时根本不执行任何操作。要检查平台是否支持捕获回溯,您可以参考 `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` 可能实际上并不会改变捕获回溯的方式。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![unstable(feature = "backtrace", issue = "53487")]

#[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::SeqCst};
use crate::sync::Once;
use crate::sys_common::backtrace::{lock, output_filename};
use crate::vec::Vec;

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

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

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()
    }
}

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(SeqCst) {
            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, SeqCst);
        enabled
    }

    /// 捕获当前线程的栈回溯。
    ///
    /// 此函数将捕获当前 OS 执行线程的栈回溯,并返回 `Backtrace` 类型,该类型以后可用于打印整个栈跟踪或将其呈现为字符串。
    ///
    /// 如果没有同时设置 `RUST_BACKTRACE` 或 `RUST_LIB_BACKTRACE` backtrace 变量,则此函数将为 noop。
    /// 如果设置并启用了任何一个环境变量,则此函数实际上将捕获回溯。
    /// 捕获回溯可能会占用大量内存并且速度很慢,因此这些环境变量允许自由使用 `Backtrace::capture`,并且仅在设置环境变量时才会导致速度降低。
    ///
    ///
    /// 要强制捕获回溯,而不管环境变量如何,请使用 `Backtrace::force_capture` 函数。
    ///
    ///
    ///
    ///
    ///
    ///
    #[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` 环境变量的值,始终捕获回溯。
    ///
    ///
    /// 请注意,在某些平台上,捕获回溯可能是一项昂贵的操作,因此在对性能敏感的代码部分中应谨慎使用。
    ///
    ///
    ///
    ///
    #[inline(never)] // 要确保这里有一个框架要删除
    pub fn force_capture() -> Backtrace {
        Backtrace::create(Backtrace::force_capture as usize)
    }

    /// 无论环境变量配置如何,都将强制捕获禁用的回溯。
    ///
    pub const fn disabled() -> Backtrace {
        Backtrace { inner: Inner::Disabled }
    }

    // 捕获一个追溯,该追溯开始于由寻址的函数之前
    // `ip`
    fn create(ip: usize) -> Backtrace {
        // SAFETY: 我们不会试图重新锁定它。
        let _lock = unsafe { 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() as usize == 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 }
    }

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

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

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 锁进行同步,然后实际解决所有问题。
        //
        // SAFETY: 我们不会试图重新锁定它。
        //
        let _lock = unsafe { 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 => 1 as *mut c_void,
        }
    }
}