timers: set{Immediate,Timeout} and general event loop clarification

[trevnorris]

Add better documentation about the event loop so people can easily understand why things like the following occur:

setImmediate(function() { console.log('setImmediate'); });
setTimeout(function() { console.log('setTimeout'); }, 0);
process.nextTick(function() { console.log('nextTick'); });

// output:
// nextTick
// setTimeout
// setImmediate

@isaacs think this should go in the standard API docs, or some other location we can reference?

[isaacs]

+1

This should go in doc/api/timers.markdown, I think.

[bnoordhuis]

Maybe link to your explanation from the process.nextTick() documentation?

On the subject of process.nextTick(), its documentation could be improved too: "It typically runs before any other I/O events fire, but there are some exceptions." - that's wrong, right? nextTick callbacks run after a callback into JS land, whether it's I/O related or not.

[trevnorris]

@bnoordhuis correct. the nextTickQueue is drained after, and only after, MakeCallback is called. That is also something that needs to be clarified.

[trevnorris]

@tjfontaine just going to voice this again. I don't think the change to run all setImmediate in a queue was correctly done. Here's now what currently happens:

function cb(arg) {
  return function() {
    console.log(arg);
    process.nextTick(function() {
      console.log('nextTick - ' + arg);
    });
  }
}


cb('0')();
setImmediate(cb('1'));
setImmediate(cb('2'));

// output:
// 0
// nextTick - 0
// 1
// 2
// nextTick - 1
// nextTick - 2

When instead the output should be:

// output
// 0
// nextTick - 0
// 1
// nextTick - 1
// 2
// nextTick - 2

If people think nextTick is confusing, it's going to be mind melting to explain how we have several queues each being resolved in their own succession. I'm rewriting the nextTick docs now and replacing I/O with asynchronous since technically it has nothing intrinsically to do with I/O. But it now has to come with a long explanation of how those callbacks are called after any synchronous callback queues have already been processed. (e.g. setImmediate or setTimeout(..., 0)).

IMO we should be checking process._tickInfoBox[0] and calling process._tickCallback() if > 0 after every callback. I've set this up so it's super cheap to do from JS or C++.

[bnoordhuis]

If people think nextTick is confusing, it's going to be mind melting to explain how we have several queues each being resolved in their own succession.

FWIW, 1 2 nextTick1 nextTick2 is what I would expect the output to be (suppressing all knowledge of node internals and putting on my layman's cap.)

(EDIT: Trevor changed the example.)

[trevnorris]

I've opened #5950 with some changes. Feel the wording here needs to be precise so looking for feedback while I write it out.

[jasnell]

@trevnorris ... assuming we can close this also since #5950 was closed.