README.md



ASAP

This asap CommonJS package contains a single asap module that
exports a single asap function that executes a function as soon as
possible.

asap(function () {
    // ...
});


More formally, ASAP provides a fast event queue that will execute tasks
until it is empty before yielding to the JavaScript engine's underlying
event-loop.  When the event queue becomes non-empty, ASAP schedules a
flush event, preferring for that event to occur before the JavaScript
engine has an opportunity to perform IO tasks or rendering, thus making
the first task and subsequent tasks semantically indistinguishable.
ASAP uses a variety of techniques to preserve this invariant on
different versions of browsers and NodeJS.

By design, ASAP can starve the event loop on the theory that, if there
is enough work to be done synchronously, albeit in separate events, long
enough to starve input or output, it is a strong indicator that the
program needs to push back on scheduling more work.

Take care.  ASAP can sustain infinite recursive calls indefinitely
without warning.  This is behaviorally equivalent to an infinite loop.
It will not halt from a stack overflow, but it will chew through
memory (which is an oddity I cannot explain at this time).  Just as with
infinite loops, you can monitor a Node process for this behavior with a
heart-beat signal.  As with infinite loops, a very small amount of
caution goes a long way to avoiding problems.

function loop() {
    asap(loop);
}
loop();


ASAP is distinct from setImmediate in that it does not suffer the
overhead of returning a handle and being possible to cancel.  For a
setImmediate shim, consider setImmediate.

If a task throws an exception, it will not interrupt the flushing of
high-priority tasks.  The exception will be postponed to a later,
low-priority event to avoid slow-downs, when the underlying JavaScript
engine will treat it as it does any unhandled exception.


Heritage

ASAP has been factored out of the Q asynchronous promise library.
It originally had a naïve implementation in terms of setTimeout, but
Malte Ubl provided an insight that postMessage might be
useful for creating a high-priority, no-delay event dispatch hack.
Since then, Internet Explorer proposed and implemented setImmediate.
Robert Kratić began contributing to Q by measuring the performance of
the internal implementation of asap, paying particular attention to
error recovery.  Domenic, Robert, and I collectively settled on the
current strategy of unrolling the high-priority event queue internally
regardless of what strategy we used to dispatch the potentially
lower-priority flush event.  Domenic went on to make ASAP cooperate with
NodeJS domains.

For further reading, Nicholas Zakas provided a thorough article on The
Case for setImmediate.


License

Copyright 2009-2013 by Contributors
MIT License (enclosed)