From 33d746c656d748635986a097ae74ea3208d649a2 Mon Sep 17 00:00:00 2001 From: isaacs Date: Sat, 13 Jul 2013 15:20:27 -0700 Subject: doc: Explain process.nextTick timing Provide more detailed explanation of the timing of `process.nextTick` relative to I/O. --- doc/api/process.markdown | 21 ++++++++++++++++++--- 1 file 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 -- cgit v1.2.1