doc: WIP update timers/nextTick documentation

[trevnorris]

Still in the works, but put in your 2 cents along the way.

[bnoordhuis]

Something like "Schedules a callback to run as soon as possible but no sooner."? (Half tongue in cheek.)

[isaacs]

Apart from teh nit about stability level, lgtm.

[tjfontaine]

I would like to deemphasize this in favor of setImmediate it would be nice to call it out here that because of the starvation warning that it's strongly advised that users now use setImmediate

[trevnorris]

True that.

[sam-github]

So, I used to know why to call .nextTick(), but then @bnoordhuis made
.setImmediate() much faster, and I think @trevnorris removed the
problems/limits on recursive call of .nextTick(), and I no longer
understand why you would use one vs the other.

Can someone explain why node shouldn't just do process.nextTick = process.setImmediate?

And make some clear statement in the docs about under what circumstances
one should be used, vs the other?

Most reasonable use for deferred callbacks is when returning an EE, and
wanting to give caller a chance to listen on events. Next most reasonable
is when an API is usually async, and you want to make sure it is always
async.

In those cases, is the prefered API now .setImmediate, or is it still
.nextTick?

[xk]

AFAIK setImmediate(f) is conceptually === setTimeout(f, 0)

The setImmediate queue is dispatched only once per event loop turn, like so:

1.- Grab the setImmediateQueue, call it currentSetImmediateQueue,
2.- Put a new, empty, setImmediateQueue in its place
3.- Call everything that's in the currentSetImmediateQueue

But the netTick queue is serviced more than once, as often as needed per event loop turn, like so:

while (nextTickQueue.length) nextTickQueue.shift()()

So:

1.- When you add an item to the nextTickQueue from a function in the nextTickQueue, it will simply make that while() loop above loop once more, but when you add an item to the setImmediateQueue, the newly added item won't run until the next turn of the event loop (and many other callbacks may have been called in-between, by then)
2.- Recursively adding to the nextTickQueue blocks the event loop.
3.- Recursively adding to the setImmediateQueue does not block the event loop.
4.- If you want to be totally sure that no other callback (*) runs before f, use .nextTick(f).

(*) Any other cb that was already in the nextTickQueue will still run before f, though.

[tjfontaine]

what @xk says is right, I would like to add the emphasis that when you do queue with setImmediate you are sure to always get called on the next turn of the event loop, where as nextTick's queue can be cleared multiple times as people transition through MakeCallback.

The fact that this logic makes it nice to make sure your cb will fire "before" others, is a side effect and shouldn't be relied upon outside of core anyway, hence my insistence to deemphasize the use of nextTick in general.

(Also nextTick doesn't and likely won't take arguments to be passed to the function)

[mrhooray]

So is it safe to say we can just use setImmediate unless we want to make sure cb is called at the beginning of next tick(except reaching maxTickDepth)? And cb of setImmediate will be significantly delayed if long blocking code gets called by i/o events before immediates?

[tjfontaine]

It's safe to say, you want to use setImmediate unless there is clear evidence that you need this callback to run before any other IO notification. Out side of core I am skeptical that that distinction means anything to anyone as you have no real visibility into what actually is happening, so it's just always preferred to use setImmediate

[trevnorris]

process.nextTick() will run something asynchronously, but before the event loop has a chance to continue. setImmediate runs at the end of each event loop.

[trevnorris]

I'll resurrect this soon as I get through the stuff that's on fire.

[jasnell]

@trevnorris ... is this still on your todo list ;-)

[trevnorris]

@jasnell hah. nope.

[trevnorris]

Closing. If someone wants to take this on and polish it up feel free.