diff --git a/doc/api/process.markdown b/doc/api/process.markdown index 0905d45c85..cfab68b868 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 event loop turn 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