Remove multiprocess finalizer and improve subprocess docs

.travis.yml

@@ -84,7 +84,7 @@ before_install:
   - uname -a
   - lsb_release -a
 install:
-  - pip install tox
+  - pip install tox travispls
   - virtualenv --version
   - easy_install --version
   - pip --version
@@ -111,7 +111,7 @@ install:
     fi
     set +x
 script:
-  - tox -v
+  - travis-pls tox -v
 after_failure:
   - more .tox/log/* | cat
   - more .tox/*/log/* | cat

appveyor.yml

@@ -8,7 +8,7 @@ environment:
     - TOXENV: 'py27-t310-c45,py27-t40-c45,py27-t41-c45'
     - TOXENV: 'py34-t310-c45,py34-t40-c45,py34-t41-c45'
     - TOXENV: 'py35-t310-c45,py35-t40-c45,py35-t41-c45'
-    - TOXENV: 'pypy-t310-c45,pypy-t40-c45,pypy-t41-c45,pypy3-t310-c45,pypy3-t40-c45,pypy3-t41-c45'
+    - TOXENV: 'pypy-t310-c45,pypy-t40-c45,pypy-t41-c45'
 
 init:
   - ps: echo $env:TOXENV

ci/bootstrap.py

@@ -52,7 +52,7 @@
 
     template_vars = {'tox_environments': tox_environments}
     for py_ver in '27 34 35 py'.split():
-        template_vars['py%s_environments' % py_ver] = [x for x in tox_environments if x.startswith('py' + py_ver)]
+        template_vars['py%s_environments' % py_ver] = [x for x in tox_environments if x.startswith('py' + py_ver + '-')]
 
     for name in os.listdir(join("ci", "templates")):
         with open(join(base_path, name), "w") as fh:

ci/templates/.travis.yml

@@ -24,7 +24,7 @@ before_install:
   - uname -a
   - lsb_release -a
 install:
-  - pip install tox
+  - pip install tox travispls
   - virtualenv --version
   - easy_install --version
   - pip --version
@@ -51,7 +51,7 @@ install:
     fi
     set +x
 script:
-  - tox -v
+  - travis-pls tox -v
 after_failure:
   - more .tox/log/* | cat
   - more .tox/*/log/* | cat

docs/index.rst

@@ -11,7 +11,7 @@ Contents:
     reporting
     debuggers
     xdist
-    mp
+    subprocess-support
     plugins
     markers-fixtures
     changelog

docs/subprocess-support.rst

@@ -0,0 +1,146 @@
+==================
+Subprocess support
+==================
+
+Normally coverage writes the data via a pretty standard atexit handler. However, if the subprocess doesn't exit on its
+own then the atexit handler might not run. Why that happens is best left to the adventurous to discover by waddling
+though the Python bug tracker.
+
+pytest-cov supports subprocesses and multiprocessing, and works around these atexit limitations. However, there are a
+few pitfalls that need to be explained.
+
+If you use ``multiprocessing.Pool``
+===================================
+
+In **pytest-cov 2.6** and older a multiprocessing finalizer is automatically registered. The finalizer will only run
+reliably if the pool is closed. If you use ``multiprocessing.Pool.terminate`` or the context manager API (``__exit__``
+will just call ``terminate``) then the workers can get SIGTERM and then the finalizers won't run or complete in time.
+Thus you need to make sure your ``multiprocessing.Pool`` gets a nice and clean exit:
+
+.. code-block:: python
+
+    from multiprocessing import Pool
+
+    def f(x):
+        return x*x
+
+    if __name__ == '__main__':
+        p = Pool(5)
+        try:
+            print(p.map(f, [1, 2, 3]))
+        finally:
+            p.close()  # Marks the pool as closed.
+            p.join()   # Waits for workers to exit.
+
+
+In **pytest-cov 2.7** a SIGTERM handler is also automatically registered if multiprocessing is used. Thus you can use
+the convenient context manger API:
+
+.. code-block:: python
+
+    from multiprocessing import Pool
+
+    def f(x):
+        return x*x
+
+    if __name__ == '__main__':
+        with Pool(5) as p:
+            print(p.map(f, [1, 2, 3]))
+
+If you use ``multiprocessing.Process``
+======================================
+
+There's similar issue when using the ``Process`` objects. Don't forget to use ``.join()``:
+
+.. code-block:: python
+
+    from multiprocessing import Process
+
+    def f(name):
+        print('hello', name)
+
+    if __name__ == '__main__':
+        p = Process(target=f, args=('bob',))
+        try:
+            p.start()
+        finally:
+            p.join()  # necessary so that the Process exists before the test suite exits (thus coverage is collected)
+
+.. _cleanup_on_sigterm:
+
+If you got custom signal handling
+=================================
+
+**pytest-cov 2.6** has a rudimentary ``pytest_cov.embed.cleanup_on_sigterm`` you can use to register a SIGTERM handler
+that flushes the coverage data.
+
+**pytest-cov 2.7** adds a ``pytest_cov.embed.cleanup_on_signal`` function and changes the implementation to be more
+robust: the handler will call the previous handler (if you had previously registered any), and is re-entrant (will
+defer extra signals if delivered while the handler runs).
+
+For example, if you reload on SIGHUP you should have something like this:
+
+.. code-block:: python
+
+    import os
+    import signal
+
+    def restart_service(frame, signum):
+        os.exec( ... )  # or whatever your custom signal would do
+    signal.signal(signal.SIGHUP, restart_service)
+
+    try:
+        from pytest_cov.embed import cleanup_on_signal
+    except ImportError:
+        pass
+    else:
+        cleanup_on_signal(signal.SIGHUP)
+
+Note that both ``cleanup_on_signal`` and ``cleanup_on_sigterm`` will run the previous signal handler.
+
+Alternatively you can do this:
+
+.. code-block:: python
+
+    import os
+    import signal
+
+    try:
+        from pytest_cov.embed import cleanup
+    except ImportError:
+        cleanup = None
+
+    def restart_service(frame, signum):
+        if cleanup is not None:
+            cleanup()
+
+        os.exec( ... )  # or whatever your custom signal would do
+    signal.signal(signal.SIGHUP, restart_service)
+
+If you use Windows
+==================
+
+On Windows you can register a handler for SIGTERM but it doesn't actually work. However you can have a working handler
+for SIGBREAK:
+
+.. code-block:: python
+
+    import os
+    import signal
+
+    def shutdown(frame, signum):
+        # your app's shutdown or whatever
+    signal.signal(signal.SIGBREAK, shutdown)
+
+    try:
+        from pytest_cov.embed import cleanup_on_signal
+    except ImportError:
+        pass
+    else:
+        cleanup_on_signal(signal.SIGBREAK)
+
+Note that `SIGBREAK is tricky
+<https://stefan.sofa-rockers.org/2013/08/15/handling-sub-process-hierarchies-python-linux-os-x/>`_:
+
+* you need to deliver ``signal.CTRL_BREAK_EVENT``
+* it gets delivered to the whole process group, and that can have unforeseen consequences

src/pytest_cov/embed.py

@@ -16,13 +16,16 @@
 import os
 import signal
 
-active_cov = None
+_active_cov = None
 
 
 def multiprocessing_start(_):
+    global _active_cov
     cov = init()
     if cov:
-        multiprocessing.util.Finalize(None, cleanup, args=(cov,), exitpriority=1000)
+        _active_cov = cov
+        multiprocessing.util.Finalize(None, cleanup, exitpriority=1000)
+        cleanup_on_sigterm()
 
 
 try:
@@ -36,7 +39,7 @@ def multiprocessing_start(_):
 def init():
     # Only continue if ancestor process has set everything needed in
     # the env.
-    global active_cov
+    global _active_cov
 
     cov_source = os.environ.get('COV_CORE_SOURCE')
     cov_config = os.environ.get('COV_CORE_CONFIG')
@@ -56,7 +59,7 @@ def init():
             cov_config = True
 
         # Activate coverage for this process.
-        cov = active_cov = coverage.Coverage(
+        cov = _active_cov = coverage.Coverage(
             source=cov_source,
             branch=cov_branch,
             data_suffix=True,
@@ -77,26 +80,36 @@ def _cleanup(cov):
         cov.save()
 
 
-def cleanup(cov=None):
-    global active_cov
+def cleanup():
+    global _active_cov
+    global _cleanup_in_progress
+    global _pending_signal
 
-    _cleanup(cov)
-    if active_cov is not cov:
-        _cleanup(active_cov)
-    active_cov = None
+    _cleanup_in_progress = True
+    _cleanup(_active_cov)
+    _active_cov = None
+    if _pending_signal:
+        _signal_cleanup_handler(*_pending_signal)
+        _pending_signal = None
 
 
 multiprocessing_finish = cleanup  # in case someone dared to use this internal
 
 _previous_handlers = {}
+_pending_signal = None
+_cleanup_in_progress = False
 
 
 def _signal_cleanup_handler(signum, frame):
+    global _pending_signal
+    if _cleanup_in_progress:
+        _pending_signal = signum, frame
+        return
     cleanup()
     _previous_handler = _previous_handlers.get(signum)
     if _previous_handler == signal.SIG_IGN:
         return
-    elif _previous_handler:
+    elif _previous_handler and _previous_handler is not _signal_cleanup_handler:
         _previous_handler(signum, frame)
     elif signum == signal.SIGTERM:
         os._exit(128 + signum)
@@ -105,8 +118,10 @@ def _signal_cleanup_handler(signum, frame):
 
 
 def cleanup_on_signal(signum):
-    _previous_handlers[signum] = signal.getsignal(signum)
-    signal.signal(signum, _signal_cleanup_handler)
+    previous = signal.getsignal(signum)
+    if previous is not _signal_cleanup_handler:
+        _previous_handlers[signum] = previous
+        signal.signal(signum, _signal_cleanup_handler)
 
 
 def cleanup_on_sigterm():

src/pytest_cov/plugin.py

@@ -118,7 +118,6 @@ def __init__(self, options, pluginmanager, start=True):
 
         # Our implementation is unknown at this time.
         self.pid = None
-        self.cov = None
         self.cov_controller = None
         self.cov_report = compat.StringIO()
         self.cov_total = None
@@ -286,12 +285,10 @@ def pytest_runtest_setup(self, item):
         if os.getpid() != self.pid:
             # test is run in another process than session, run
             # coverage manually
-            self.cov = embed.init()
+            embed.init()
 
     def pytest_runtest_teardown(self, item):
-        if self.cov is not None:
-            embed.cleanup(self.cov)
-            self.cov = None
+        embed.cleanup()
 
     @compat.hookwrapper
     def pytest_runtest_call(self, item):