invoicer/node_modules/asap

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)