regrtest: use faulthandler to dump the tracebacks on SIGUSR1

Lib/test/regrtest.py

 #! /usr/bin/env python3
 
 """
 Usage:
 
 python -m test [options] [test_name1 [test_name2 ...]]
 python path/to/Lib/test/regrtest.py [options] [test_name1 [test_name2 ...]]
 
 
 If no arguments or options are provided, finds all files matching
@@ skipping 142 matching lines @@
     subprocess  Run all tests for the subprocess module.
 
     urlfetch -  It is okay to download files required on testing.
 
     gui -       Run tests that require a running GUI.
 
 To enable all resources except one, use '-uall,-<resource>'.  For
 example, to run all the tests except for the gui tests, give the
 option '-uall,-gui'.
 """
+USAGE_SIGUSR1 = """
+You can send a SIGUSR1 signal to display the traceback of the current threads.

[eric.araujo, 2011/05/23 16:26:18]

“the traceback” (singular) “of the current threads” (plural) sounds a bit
strange to me: There is one traceback for many threads?

+But send a signal may interrupt the current system call and so interfer with

[eric.araujo, 2011/05/23 16:26:18]

“Note that sending a signal may interrupt a system call in progress and thus
interfere with the tests, so only do it if a test hangs and you want to know
where.”

+the tests, only do that if a test hangs and you would like to know where.
+"""
 
 import builtins
+import errno
 import faulthandler
 import getopt
+import io
 import json
 import os
 import random
 import re
-import io
+import signal
 import sys
 import time
-import errno
 import traceback
+import unittest
 import warnings
-import unittest
 from inspect import isabstract
 import tempfile
 import platform
 import sysconfig
 import logging
 
 
 # Some times __path__ and __file__ are not absolute (e.g. while running from
 # Lib/) and, if we change the CWD to run the tests in a temporary dir, some
 # imports might fail.  This affects only the modules imported before os.chdir().
@@ skipping 73 matching lines @@
 
     The other default arguments (verbose, quiet, exclude,
     single, randomize, findleaks, use_resources, trace, coverdir,
     print_slow, and random_seed) allow programmers calling main()
     directly to set the values that would normally be set by flags
     on the command line.
     """
 
     # Display the Python traceback fatal errors (e.g. segfault)
     faulthandler.enable(all_threads=True)
+    if hasattr(signal, 'SIGUSR1'):
+        faulthandler.register(signal.SIGUSR1)
 
     if hasattr(faulthandler, 'dump_tracebacks_later'):
         timeout = 60*60
     else:
         timeout = None
 
     replace_stdout()
 
     support.record_original_stdout(sys.stdout)
     try:
         opts, args = getopt.getopt(sys.argv[1:], 'hvqxsSrf:lu:t:TD:NLR:FwWM:nj:',
             ['help', 'verbose', 'verbose2', 'verbose3', 'quiet',
              'exclude', 'single', 'slow', 'random', 'fromfile', 'findleaks',
              'use=', 'threshold=', 'trace', 'coverdir=', 'nocoverdir',
              'runleaks', 'huntrleaks=', 'memlimit=', 'randseed=',
              'multiprocess=', 'coverage', 'slaveargs=', 'forever', 'debug',
              'start=', 'nowindows', 'header', 'testdir=', 'timeout=', 'wait'])
     except getopt.error as msg:
         usage(msg)
 
     # Defaults
     if random_seed is None:
         random_seed = random.randrange(10000000)
     if use_resources is None:
         use_resources = []
     debug = False
     start = None
     for o, a in opts:
         if o in ('-h', '--help'):
-            print(__doc__)
+            usage = __doc__
+            if hasattr(signal, 'SIGUSR1'):
+                usage += USAGE_SIGUSR1
+            print(usage)
             return
         elif o in ('-v', '--verbose'):
             verbose += 1
         elif o in ('-w', '--verbose2'):
             verbose2 = True
         elif o in ('-d', '--debug'):
             debug = True
         elif o in ('-W', '--verbose3'):
             verbose3 = True
         elif o in ('-q', '--quiet'):
@@ skipping 1303 matching lines @@
     assert __file__ == os.path.abspath(sys.argv[0])
 
     TEMPDIR, TESTCWD = _make_temp_dir_for_build(TEMPDIR)
 
     # Run the tests in a context manager that temporary changes the CWD to a
     # temporary and writable directory. If it's not possible to create or
     # change the CWD, the original CWD will be used. The original CWD is
     # available from support.SAVEDCWD.
     with support.temp_cwd(TESTCWD, quiet=True):
         main()