Module std::backtrace[−][src]

🔬 This is a nightly-only experimental API. (backtrace #53487)
Expand description

支持捕获 OS 线程的栈回溯

该模块包含从 OS 线程本身捕获正在运行的 OS 线程的栈回溯所必需的支持。 Backtrace 类型支持通过 Backtrace::capture 和 Backtrace::force_capture 函数捕获栈跟踪。

回溯通常很容易附加到错误 (例如，实现 std::error::Error 的类型) 上，以获取产生错误的因果关系。

Note: 该模块是不稳定的，并且是在 RFC 2504 中设计的，因此您 可以在 tracking issue 中了解有关其状态的更多信息。

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

Structs

BacktraceExperimental

捕获的 OS 线程栈回溯。

BacktraceFrameExperimental

回溯的单个帧。

Enums

BacktraceStatusExperimental

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