implement setImmediate

[tjfontaine]

This is a basic implementation of setImmediate from https://dvcs.w3.org/hg/webperf/raw-file/tip/specs/setImmediate/Overview.html

I followed the spirit of the async queue, yielding after each iteration. I did not implement the integer id but followed the opaque object from the other timer types.

Tests and documentation will be forthcoming.

[bnoordhuis]

It's never reassigned so use function processImmediate() { here.

[medikoo]

Shouldn't setImmediate be just alias of process.nextTick? What's the difference?

[tjfontaine]

The semantics of process.nextTick have changed for 0.9 and forward (see #3723) so there is a need for something new.

The main difference between nextTick and setImmediate is that between each scheduled immediate that is processed it yields time back to the event loop until the timer is scheduled again, in this case the timer is 0 so it happens on the next trip through the event processing.

Another small difference is that you can pass arguments to the function provided

[isaacs]

Also, setImmediate returns a handle that can be passed to clearImmediate to
cancel it.

[medikoo]

Thanks for clarification! So I assume that apart from obvious API differences (arguments, and clear handle), difference lies in fact that setImmediate sits on top of timers (is handled by them) and nextTick is more low-level and is handled before and outside of timers logic.

I understand then, that on Node.js ground setImmediate(fn) would have exactly same effect as setTimeout(fn, 0)?

Do timers logic in some significant way delay execution of (what would be) setImmediate callback when compared to nextTick callback?

[tjfontaine]

I will try and layout the differences of all the deferral mechanisms including the proposed setImmediate

• process.nextTick
  • fired from tick spinner, no timer objects allocated
  • executes up to process.maxTickDepth queued callbacks before yielding to event loop
  • for 10 consecutive process.nextTick 0 allocated timers, 0 yields to event loop
• setTimeout
  • All related idle times fall into a similar bucket, one timer allocated per bucket
  • fired from event loop
  • executes all queued callbacks for idle time without yielding to event loop
  • destroys timer
  • for 10 consecutive setTimeout(x, 0) 1 timer allocated, 0 yields to event loop
• setInterval
  • timer object allocated per setInterval call, destroy'ed on clearInterval
  • each fired from event loop based on the loops scheduling
  • for 10 consecutive setInterval(x, 0) 10 timers allocated, 0 yields to event loop
• setImmediate
  • single module scoped timer object allocated
  • after execution of each queued callback yield to event loop
  • for 10 consecutive setImmediate(x) 1 module allocated timer, 10 yields to event loop

[bnoordhuis]

Make this one line. I say that because if I don't complain about it, @isaacs will - he is like that.

[bnoordhuis]

Generally LGTM, both conceptually and implementation-wise, but will need tests and documentation, of course.

@isaacs Agreed?

[tjfontaine]

I have added a test and documentation

[bnoordhuis]

Thanks Timothy, landed in 382f22f.

[tjfontaine]

thanks!