"faulthandler" --- Volcar el rastreo de Python
**********************************************

Nuevo en la versión 3.3.

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

Este módulo contiene funciones para volcar los rastreos de Python
explícitamente, en un fallo, después de un tiempo de espera o en una
señal del usuario. Llame a "faulthandler.enable()" para instalar los
gestores de fallos para las señales "SIGSEGV", "SIGFPE", "SIGABRT",
"SIGBUS", y "SIGILL". También puede activarlos al inicio estableciendo
la variable de entorno "PYTHONFAULTHANDLER" o usando la opción de
línea de comandos "-X" "faulthandler".

El gestor de fallos es compatible con el gestor de fallos del sistema
como Apport o el gestor de fallos de Windows. El módulo utiliza una
pila alternativa para los gestores de señales si la función
"sigaltstack()" está disponible. Esto le permite volcar el rastreo
incluso en un desbordamiento de pila.

El gestor de fallos se llama en casos catastróficos y, por lo tanto,
solo puede utilizar funciones seguras en señales (por ejemplo, no
puede asignar memoria en el *heap*). Debido a esta limitación, el
volcado del rastreo es mínimo comparado a los rastreos normales de
Python:

* Solo se soporta ASCII. El gestor de errores "backslashreplace" se
  utiliza en la codificación.

* Cada cadena de caracteres está limitada a 500 caracteres.

* Solo se muestran el nombre de archivo, el nombre de la función y el
  número de línea. (sin código fuente)

* Está limitado a 100 *frames* y 100 hilos.

* El orden se invierte: la llamada más reciente se muestra primero.

Por defecto, el rastreo de Python se escribe en "sys.stderr". Para ver
los rastreos, las aplicaciones deben ejecutarse en la terminal.
Alternativamente se puede pasar un archivo de registro a
"faulthandler.enable()".

El módulo está implementado en C, así los rastreos se pueden volcar en
un fallo o cuando Python está en bloqueo mutuo.


Volcar el rastreo
=================

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

   Vuelca los rastreos de todos los hilos en el archivo *file*. Si
   *all_threads* es "False", vuelca solo el hilo actual.

   Distinto en la versión 3.5: Se añadió soporte para pasar el
   descriptor de archivo a esta función.


Estado del gestor de fallos
===========================

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

   Activa el gestor de fallos: instala gestores para las señales
   "SIGSEGV", "SIGFPE", "SIGABRT", "SIGBUS" y "SIGILL" para volcar el
   rastreo de Python. Si *all_threads* es "True", produce rastreos por
   cada hilo activo. De lo contrario, vuelca solo el hilo actual.

   El archivo *file* se debe mantener abierto hasta que se desactive
   el gestor de fallos: ver problema con descriptores de archivo.

   Distinto en la versión 3.5: Se añadió soporte para pasar el
   descriptor de archivo a esta función.

   Distinto en la versión 3.6: En Windows, también se instaló un
   gestor para la excepción de Windows.

faulthandler.disable()

   Desactiva el gestor de fallos: desinstala los gestores de señales
   instalados por "enable()".

faulthandler.is_enabled()

   Comprueba si el gestor de fallos está activado.


Volcar los rastreos después de un tiempo de espera
==================================================

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

   Vuelca los rastreos de todos los hilos, después de un tiempo de
   espera de *timeout* segundos, o cada *timeout* segundos si *repeat*
   es "True". Si *exit* es "True", llama a "_exit()" con status=1
   después de volcar los rastreos. (Nota: "_exit()" termina el proceso
   inmediatamente, lo que significa que no hace ninguna limpieza como
   vaciar los buffers de archivos.) Si la función se llama dos veces,
   la nueva llamada reemplaza los parámetros previos y reinicia el
   tiempo de espera. El temporizador tiene una resolución de menos de
   un segundo.

   El archivo *file* se debe mantener abierto hasta que se vuelque el
   rastreo o se llame a "cancel_dump_traceback_later()": ver problema
   con descriptores de archivo.

   Esta función está implementada utilizando un hilo vigilante.

   Distinto en la versión 3.7: Ahora esta función está siempre
   disponible.

   Distinto en la versión 3.5: Se añadió soporte para pasar el
   descriptor de archivo a esta función.

faulthandler.cancel_dump_traceback_later()

   Cancela la última llamada a "dump_traceback_later()".


Volcar el rastreo en una señal del usuario
==========================================

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

   Registra una señal del usuario: instala un gestor para la señal
   *signum* para volcar el rastreo de todos los hilos, o del hilo
   actual si *all_threads* es "False", en el archivo *file*. Llama al
   gestor previo si *chain* es "True".

   El archivo *file* se debe mantener abierto hasta que la señal sea
   anulada por "unregister()": ver problema con descriptores de
   archivo.

   No está disponible en Windows.

   Distinto en la versión 3.5: Se añadió soporte para pasar el
   descriptor de archivo a esta función.

faulthandler.unregister(signum)

   Anula una señal del usuario: desinstala el gestor de la señal
   *signum* instalada por "register()". Retorna "True" si la señal fue
   registrada, "False" en otro caso.

   No está disponible en Windows.


Problema con descriptores de archivo
====================================

"enable()", "dump_traceback_later()" y "register()" guardan el
descriptor de archivo de su argumento *file*. Si se cierra el archivo
y su descriptor de archivo es reutilizado por un nuevo archivo, o si
se usa "os.dup2()" para reemplazar el descriptor de archivo, el
rastreo se escribirá en un archivo diferente. Llame a estas funciones
nuevamente cada vez que se reemplace el archivo.


Ejemplo
=======

Ejemplo de un fallo de segmentación en Linux con y sin activar el
gestor de fallos:

   $ 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
