unix: make loops and watchers usable after fork()

Added the uv_loop_fork() API that must be called in a child process to
continue using an existing loop. Internally this calls a uv__io_fork
function for each supported platform, similar to the way
uv__platform_loop_init works.

After this call, existing and new IO, async and signal watchers will
contiue working as before on all platforms, as will the
threadpool (although any threads it was using are of course gone).

On Linux and BSDs that use kqueue, existing and new fsevent watchers
will also continue to work as expected. On OS X, though, directory
fsevents will not be able to use the optimized CoreFoundation path if
they had already been used in the parent process, instead falling back
to the kqueue path used on other BSDs.

Existing fsevent watchers will not function on AIX or SunOS. This
could be relatively easily fixed by someone with AIX knowledge in the
future, but SunOS will require some additional work to keep track if
the watchers.

A new test file, test/test-fork.c, was added to contain fork-related
tests to verify functionality in the child process.

PR-URL: https://github.com/libuv/libuv/pull/846
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>

1 files changed, 49 insertions, 0 deletions

diff --git a/docs/src/loop.rst b/docs/src/loop.rst
index 1f504cb3..b3fa069e 100644
--- a/docs/src/loop.rst
+++ b/docs/src/loop.rst
@@ -165,3 +165,52 @@ API
 .. c:function:: void uv_walk(uv_loop_t* loop, uv_walk_cb walk_cb, void* arg)
 
     Walk the list of handles: `walk_cb` will be executed with the given `arg`.
+
+.. c:function:: int uv_loop_fork(uv_loop_t* loop)
+
+    .. versionadded:: 1.12.0
+
+    Reinitialize any kernel state necessary in the child process after
+    a :man:`fork(2)` system call.
+
+    Previously started watchers will continue to be started in the
+    child process.
+
+    It is necessary to explicitly call this function on every event
+    loop created in the parent process that you plan to continue to
+    use in the child, including the default loop (even if you don't
+    continue to use it in the parent). This function must be called
+    before calling :c:func:`uv_run` or any other API function using
+    the loop in the child. Failure to do so will result in undefined
+    behaviour, possibly including duplicate events delivered to both
+    parent and child or aborting the child process.
+
+    When possible, it is preferred to create a new loop in the child
+    process instead of reusing a loop created in the parent. New loops
+    created in the child process after the fork should not use this
+    function.
+
+    This function is not implemented on Windows, where it returns ``UV_ENOSYS``.
+
+    .. note::
+
+        On Mac OS X, if directory FS event handles were in use in the
+        parent process *for any event loop*, the child process will no
+        longer be able to use the most efficient FSEvent
+        implementation. Instead, uses of directory FS event handles in
+        the child will fall back to the same implementation used for
+        files and on other kqueue-based systems.
+
+    .. caution::
+
+       On AIX and SunOS, FS event handles that were already started in
+       the parent process at the time of forking will *not* deliver
+       events in the child process; they must be closed and restarted.
+       On all other platforms, they will continue to work normally
+       without any further intervention.
+
+    .. caution::
+
+       Any previous value returned from :c:func`uv_backend_fd` is now
+       invalid. That function must be called again to determine the
+       correct backend file descriptor.