diff options
| author | Ned Batchelder <ned@nedbatchelder.com> | 2022-01-23 07:15:08 -0500 |
|---|---|---|
| committer | Ned Batchelder <ned@nedbatchelder.com> | 2022-01-23 13:44:58 -0500 |
| commit | dd575eec0fa173bcb6c680d2f1c822a28280d011 (patch) | |
| tree | 44992b89c286d9c8bb86478f2e70c03616e54a11 /doc/subprocess.rst | |
| parent | 2e8c1910cad1ba23726e62e03c4ae1608f3fb26e (diff) | |
| download | python-coveragepy-git-dd575eec0fa173bcb6c680d2f1c822a28280d011.tar.gz | |
fix: save data on SIGTERM #1307
This covers multiprocessing.Process.terminate(), and maybe other cases also.
Diffstat (limited to 'doc/subprocess.rst')
| -rw-r--r-- | doc/subprocess.rst | 27 |
1 files changed, 13 insertions, 14 deletions
diff --git a/doc/subprocess.rst b/doc/subprocess.rst index b28cbc91..777ffbae 100644 --- a/doc/subprocess.rst +++ b/doc/subprocess.rst @@ -25,7 +25,7 @@ the name of the :ref:`configuration file <config>` to use. .. note:: - If you have subprocesses because you are using :mod:`multiprocessing + If you have subprocesses created with :mod:`multiprocessing <python:multiprocessing>`, the ``--concurrency=multiprocessing`` command-line option should take care of everything for you. See :ref:`cmd_run` for details. @@ -34,8 +34,8 @@ When using this technique, be sure to set the parallel option to true so that multiple coverage.py runs will each write their data to a distinct file. -Configuring Python for sub-process coverage -------------------------------------------- +Configuring Python for sub-process measurement +---------------------------------------------- Measuring coverage in sub-processes is a little tricky. When you spawn a sub-process, you are invoking Python to run your program. Usually, to get @@ -84,18 +84,17 @@ start-up. Be sure to remove the change when you uninstall coverage.py, or use a more defensive approach to importing it. -Signal handlers and atexit --------------------------- - -.. hmm, this isn't specifically about subprocesses, is there a better place - where we could talk about this? +Process termination +------------------- To successfully write a coverage data file, the Python sub-process under -analysis must shut down cleanly and have a chance for coverage.py to run the -``atexit`` handler it registers. +analysis must shut down cleanly and have a chance for coverage.py to run its +termination code. It will do that when the process ends naturally, or when a +SIGTERM signal is received. -For example if you send SIGTERM to end the sub-process, but your sub-process -has never registered any SIGTERM handler, then a coverage file won't be -written. See the `atexit`_ docs for details of when the handler isn't run. +Coverage.py uses :mod:`atexit <python:atexit>` to handle usual process ends, +and a :mod:`signal <python:signal>` handler to catch SIGTERM signals. -.. _atexit: https://docs.python.org/3/library/atexit.html +Other ways of ending a process, like SIGKILL or :func:`os._exit +<python:os._exit>`, will prevent coverage.py from writing its data file, +leaving you with incomplete or non-existent coverage data. |