Module std::backtrace

1.65.0 · source ·
Expand description

支持捕获 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 可能实际上不会改变回溯的捕获方式。

Structs

Enums

  • BacktraceStatus
    回溯的当前状态，指示它是否已捕获或由于其他原因而为空。