"faulthandler" —— 转储 Python 的跟踪信息
****************************************

3.3 版新加入.

======================================================================

当故障、超时或收到用户信号时，利用本模块内的函数可转储 Python 跟踪信息
。调用 "faulthandler.enable()" 可安装 "SIGSEGV" 、 "SIGFPE" 、
"SIGABRT" 、 "SIGBUS"  和 "SIGILL" 信号的故障处理程序。通过设置
"PYTHONFAULTHANDLER" 环境变量或 "-X"  "faulthandler" 命令行参数，还可
以在启动时开启这些设置。

故障处理程序与操作系统的故障处理程序兼容，比如 Apport 或 Windows 故障
处理程序等。如果 "sigaltstack()" 函数可用，本模块将为信号处理程序使用
备用堆栈。这样即便堆栈溢出也能转储跟踪信息。

故障处理程序将在灾难性场合调用，因此只能使用信号安全的函数（比如不能在
堆上分配内存）。由于这一限制，与正常的 Python 跟踪相比，转储量是最小的
。

* 只支持 ASCII 码。编码时会用到  "backslashreplace" 错误处理程序。

* 每个字符串限制在 500 个字符以内。

* 只会显式文件名、函数名和行号。（不显示源代码）

* 上限是 100 页内存帧和 100 个线程。

* 反序排列：最近的调用最先显示。

默认情况下，Python 的跟踪信息会写入 "sys.stderr"。为了能看到跟踪信息，
应用程序必须运行于终端中。日志文件也可以传给 "faulthandler.enable()"。

本模块是用 C 语言实现的，所以才能在崩溃或 Python 死锁时转储跟踪信息。


转储跟踪信息
============

faulthandler.dump_traceback(file=sys.stderr, all_threads=True)

   将所有线程的跟踪数据转储到 *file* 中。如果 *all_threads* 为 "False"
   ，则只转储当前线程。

   3.5 版更變: 增加了向本函数传入文件描述符的支持。


错误处理程序的状态
==================

faulthandler.enable(file=sys.stderr, all_threads=True)

   启用故障处理程序：为 "SIGSEGV" 、 "SIGFPE" 、 "SIGABRT" 、 "SIGBUS"
   和 "SIGILL" 信号安装处理程序，以转储 Python 跟踪信息。如果
   *all_threads* 为 "True"，则会为每个运行中的线程生成跟踪信息。否则只
   转储当前线程。

   该 *文件* 必须保持打开状态，直至禁用故障处理程序为止：参见 文件描述
   符相关话题。

   3.5 版更變: 增加了向本函数传入文件描述符的支持。

   3.6 版更變: 在 Windows 系统中，同时会安装一个 Windows 异常处理程序
   。

faulthandler.disable()

   停用故障处理程序：卸载由 "enable()" 安装的信号处理程序。

faulthandler.is_enabled()

   检查故障处理程序是否被启用。


一定时间后转储跟踪数据。
========================

faulthandler.dump_traceback_later(timeout, repeat=False, file=sys.stderr, exit=False)

   在 *timeout* 秒超时后，转储所有线程的跟踪信息，如果 *repeat* 为
   "True"，则每隔 *timeout* 秒转储一次。如果 *exit* 为 "True"，则在转
   储跟踪信息后调用 "_exit()"，参数 status=1。请注意， "_exit()" 会立
   即关闭进程，这意味着不做任何清理工作，如刷新文件缓冲区等。如果调用
   两次函数，则新的调用将取代之前的参数，超时时间也会重置。计时器的精
   度为亚秒级。

   *file* 必须保持打开状态，直至跟踪信息转储完毕，或调用了
   "cancel_dump_traceback_later()"  ：参见 文件描述符相关话题。

   本函数用一个看门狗线程实现。

   3.7 版更變: 该函数现在总是可用。

   3.5 版更變: 增加了向本函数传入文件描述符的支持。

faulthandler.cancel_dump_traceback_later()

   取消 "dump_traceback_later()" 的最后一次调用。


转储用户信号的跟踪信息。
========================

faulthandler.register(signum, file=sys.stderr, all_threads=True, chain=False)

   注册一个用户信号：为 *signum* 信号安装一个处理程序，将所有线程或当
   前线程（*all_threads* 为 "False" 时）的跟踪信息转储到 *file* 中。如
   果 chain 为 "True"，则调用前一个处理程序。

   *file* 必须保持打开状态，直至信号被 "unregister()" 注销：参见 文件
   描述符相关话题。

   Windows 中不可用。

   3.5 版更變: 增加了向本函数传入文件描述符的支持。

faulthandler.unregister(signum)

   注销一个用户信号：卸载由 "register()" 安装的 *signum* 信号处理程序
   。如果信号已注册，返回 "True"，否则返回 "False"。

   Windows 中不可用。


文件描述符相关话题
==================

"enable()" 、 "dump_traceback_later()" 和 "register()" 保留其 *file*
参数给出的文件描述符。 如果文件关闭，文件描述符将被一个新文件重新使用
；或者用 "os.dup2()" 替换了文件描述符，则跟踪信息将被写入另一个文件。
每次文件被替换时，都会再次调用这些函数。


示例
====

在 Linux 中启用和停用内存段故障的默认处理程序：

   $ python3 -c "import ctypes; ctypes.string_at(0)"
   Segmentation fault

   $ python3 -q -X faulthandler
   >>> import ctypes
   >>> ctypes.string_at(0)
   Fatal Python error: Segmentation fault

   Current thread 0x00007fb899f39700 (most recent call first):
     File "/home/python/cpython/Lib/ctypes/__init__.py", line 486 in string_at
     File "<stdin>", line 1 in <module>
   Segmentation fault
