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 () {
    // ...
});

ASAP strives to schedule events to occur before yielding for IO, reflow, or redrawing. Each event receives an independent stack, with only platform code in parent frames and the events run in the order they are scheduled.

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 Node.js.

By design, ASAP prevents input events from being handled until the task queue is empty. If the process is busy engouh, this may cause incoming connection requests to be dropped, and may cause existing connections to inform the sender to reduce the transmission rate or stall. ASAP allows this on the theory that, if there is enough work to do, there is no sense in looking for trouble. As a consequence, however, ASAP can interrupt smooth animation, popularly dubbed “jank”. If your task can wait for reflow or rendering, consider using ASAP’s cousin setImmediate instead.

setImmediate will yield for IO, reflow, and repaint events. It also returns a handler and can be canceled. For a setImmediate shim, consider setImmediate.

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();

In browsers, 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. In NodeJS, on the other hand, if a task throws an exception, ASAP will resume flushing only if—and only after—the error is handled by domain.on("error") or process.on("uncaughtException").

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 Katić 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)