Permalink
Browse files

docs: add race warning to `child_process.kill()`

  • Loading branch information...
1 parent 12c8b27 commit 88f416a5edf248681f550741b38f93a3a6dd6472 @bnoordhuis committed Aug 3, 2011
Showing with 19 additions and 2 deletions.
  1. +19 −2 doc/api/child_processes.markdown
@@ -234,7 +234,24 @@ be sent `'SIGTERM'`. See `signal(7)` for a list of available signals.
// send SIGHUP to process
grep.kill('SIGHUP');
-Note that while the function is called `kill`, the signal delivered to the child
-process may not actually kill it. `kill` really just sends a signal to a process.
+Note that while the function is called `kill`, the signal delivered to the
+child process may not actually kill it. `kill` really just sends a signal
+to a process.
+
+Please note that the example contains a potential race condition on
+(at least) UNIX systems. Here is why:
+
+The canonical approach to starting a child process is to call `fork()` to
+create a copy of the current process, followed by a call to `execve()` to
+replace the copy with the actual child process. This runs in tandem with
+the parent process.
+
+The time between `fork()` and `execve()` is short but it's not zero.
+The child process may not have actually started when `spawn()` returns.
+Thus, if you send a signal immediately after the call to `spawn()`, it may
+end up being delivered to the copy of the current process and *not* the
+actual child process.
+
+The resulting behavior is undefined. It likely won't do what you want it to.
See `kill(2)`

0 comments on commit 88f416a

Please sign in to comment.