doc: Explain process.nextTick timingreviewme

Provide more detailed explanation of the timing of `process.nextTick`
relative to I/O.

1 files changed, 18 insertions, 3 deletions

diff --git a/doc/api/process.markdown b/doc/api/process.markdown
index 0905d45c8..5bb26cf7f 100644
--- a/doc/api/process.markdown
+++ b/doc/api/process.markdown
@@ -454,14 +454,24 @@ This will generate:
 
 ## process.nextTick(callback)
 
-On the next loop around the event loop call this callback.
+* `callback` {Function}
+
+Once the current pass through the event loop runs to completion, call
+the callback function.
+
 This is *not* a simple alias to `setTimeout(fn, 0)`, it's much more
-efficient.  It typically runs before any other I/O events fire, but there
-are some exceptions.
+efficient.  It runs before any additional I/O events (including
+timers) fire in subsequent ticks of the event loop.
 
+    console.log('start');
     process.nextTick(function() {
       console.log('nextTick callback');
     });
+    console.log('scheduled');
+    // Output:
+    // start
+    // scheduled
+    // nextTick callback
 
 This is important in developing APIs where you want to give the user the
 chance to assign event handlers after an object has been constructed,
@@ -513,6 +523,11 @@ This approach is much better:
       fs.stat('file', cb);
     }
 
+Note: the nextTick queue is completely drained on each pass of the
+event loop **before** additional I/O is processed.  As a result,
+recursively setting nextTick callbacks will block any I/O from
+happening, just like a `while(true);` loop.
+
 ## process.umask([mask])
 
 Sets or reads the process's file mode creation mask. Child processes inherit