Documentation. [skip ci]

doc/whatsnew_1_1.rst

@@ -119,6 +119,11 @@ downstream libraries, notably `gunicorn`_.
   :func:`gevent.os.waitpid` (again monkey patched by default) and
   :func:`gevent.signal.signal` (which is monkey patched only for the
   :data:`signal.SIGCHLD` case). The latter two patches are new in 1.1.
+- In gevent 1.0, use of libev child watchers (which are used
+  internally by ``gevent.subprocess``) had race conditions with
+  user-provided ``SIGCHLD`` handlers, causing many types of
+  unpredictable breakage. The two new APIs described above are
+  intended to rectify this.
 - Fork-watchers will be called, even in multi-threaded programs
   (except on Windows).
 - The default threadpool and threaded resolver work in child
@@ -138,6 +143,12 @@ possible in a monkey patched system, at least on POSIX platforms.
 .. caution:: It is not possible to use :mod:`gevent.subprocess` from
              native threads. See :mod:`gevent.subprocess` for details.
 
+.. note:: If the ``SIGCHLD`` signal is to be handled, it is important
+          to monkey patch (or directly use) both :mod:`os` and
+          :mod:`signal`; this is the default for
+          :func:`~gevent.monkey.patch_all`. Failure to do so can
+          result in the ``SIGCHLD`` signal being lost.
+
 .. tip:: All of the above entail forking a child process. Forking
 		 a child process that uses gevent, greenlets, and libev
 		 can have some unexpected consequences if the child

gevent/monkey.py

@@ -219,6 +219,9 @@ def patch_os():
     :func:`os.waitpid` with :func:`gevent.os.waitpid` (if the
     environment variable ``GEVENT_NOWAITPID`` is not defined). Does
     nothing if fork is not available.
+
+    This method must be used with :func:`patch_signal` to have proper SIGCHLD
+    handling. :func:`patch_all` calls both by default.
     """
     patch_module('os')
 
@@ -515,6 +518,9 @@ def patch_signal():
     """
     Make the signal.signal function work with a monkey-patched os.
 
+    This method must be used with :func:`patch_os` to have proper SIGCHLD
+    handling. :func:`patch_all` calls both by default.
+
     .. seealso:: :mod:`gevent.signal`
     """
     patch_module("signal")
@@ -536,7 +542,19 @@ def _check_repatching(**module_settings):
 def patch_all(socket=True, dns=True, time=True, select=True, thread=True, os=True, ssl=True, httplib=False,
               subprocess=True, sys=False, aggressive=True, Event=False,
               builtins=True, signal=True):
-    """Do all of the default monkey patching (calls every other applicable function in this module)."""
+    """
+    Do all of the default monkey patching (calls every other applicable
+    function in this module).
+
+    .. versionchanged:: 1.1
+       Issue a :mod:`warning <warnings>` if this function is called multiple times
+       with different arguments. The second and subsequent calls will only add more
+       patches, they can never remove existing patches by setting an argument to ``False``.
+    .. versionchanged:: 1.1
+       Issue a :mod:`warning <warnings>` if this function is called with ``os=False``
+       and ``signal=True``. This will cause SIGCHLD handlers to not be called. This may
+       be an error in the future.
+    """
     # Check to see if they're changing the patched list
     _warnings, first_time = _check_repatching(**locals())
     if not _warnings and not first_time:

gevent/os.py

@@ -210,6 +210,7 @@ if hasattr(os, 'fork'):
         _waitpid = os.waitpid
         _WNOHANG = os.WNOHANG
 
+        # replaced by the signal module.
         _on_child_hook = lambda: None
 
         # {pid -> watcher or tuple(pid, rstatus, timestamp)}