Getting Started

To include the source files for AsyncQueue and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.11.0/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('async-queue', function (Y) {
    // AsyncQueue is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using AsyncQueue

Creating and interacting with an AsyncQueue

AsyncQueues manage an array of callbacks that can be either simple function references or objects with specific keys. The primary methods on AsyncQueue are add and run.

When run() is invoked, each callback is executed in turn, either synchronously or via setTimeout (depending on the configuration of the callback or of the AsyncQueue instance).

Queued callbacks can also be promoted to the top of the queue or removed from it.

var q = new Y.AsyncQueue(callbackB, someTask, callbackA, callbackC);
q.add(callbackD, callbackE); // B, someTask, A, C, D, E
q.promote(callbackA);        // A, B, someTask, C, D, E
q.remove(someTask);          // A, B, C, D, E
q.run();                     // execute A, then B, then C, then D, then E

Pausing and stopping an AsyncQueue

In addition to run(), AsyncQueue instances also have pause() and stop() methods to interrupt the run state.

To wait for an external process to complete, such as an XHR request, call pause(), then run() again to resume execution.

Call stop() to terminate execution and flush the AsyncQueue.

// Seed the instance with callbacks
var q = new Y.AsyncQueue(
    MyApp.doSomething,

    // The second callback will pause the Queue and send an XHR for data
    function () {
        q.pause();

        // Send the asynchronous XHR
        Y.io(MyApp.getDataUri(), { on: {
            success : function (xid,o) {
                try {
                    var data = Y.JSON.parse(o.responseText);
                }
                catch (e) {
                    MyApp.showErrorStatus();
                    q.stop();
                }

                MyApp.processData(data);

                // In the XHR callback, restart the AsyncQueue if successful
                q.run();
            },
            failure : function () {
                MyApp.showErrorStatus();
                // Stop the AsyncQueue if anything goes wrong
                q.stop();
            }
        }});
    },

    // The third callback will do partial updates until complete
    {
        fn:    Y.bind(MyApp.updateUI,MyApp),
        until: function () {
            return MyApp.remainingData >= 0;
        }
    },
    MyApp.doSomethingElse);

q.run();

About AsyncQueue callbacks

AsyncQueue callbacks can be simple function references or object literals with the following keys:

Class- and instance-level callback defaults

AsyncQueue provides three places to configure callbacks (in decreasing precedence order):

1. The callback object
2. The AsyncQueue instance's defaults collection
3. The class static defaults collection

// All AsyncQueue instances will execute all callbacks synchronously by default
Y.AsyncQueue.defaults.timeout = -1;

var q = new Y.AsyncQueue();

// run every callback in this instance twice before moving to the next callback
q.defaults.iterations = 2;

q.add(functionA,
      {
        fn: functionB,
        timeout: 100 // this callback will be executed asynchronously
      });

// functionA executes twice immediately, then after 100 milliseconds functionB
// is executed, then after another 100ms functionB is executed again.
q.run();

Synchronous mode for callback execution

One of the main goals of the AsyncQueue is to provide a mechanism to prevent process-intensive operations from locking up the UI. By default, AsyncQueue callbacks are executed via setTimeout to facilitate this. The timeout configuration accepts -1 as a value to trigger synchronous callback execution. Use this setting with caution.

About timeout chaining

Timeout chaining is a strategy to address the lack of multithreading in JavaScript. When complex or iterative code executes it can cause the page to stop responding until the running JavaScript process completes; it can also cause "non-responsive script" or "long-running script" dialogs to be presented to the user. Both outcomes are detrimental to user experience.

To address this, the operation can be split into chunks, and setTimeout can be used to yield control back to other operations between each chunk. A common use case for this technique is to allow browser reflows to display DOM modifications incrementally while batches of work are being done in JavaScript. For iterative functions, the code can execute a portion of the overall work, then schedule itself to run via setTimeout.

The basic form of an iterative timeout chain is:

(function () {

    /* do a chunk of the work */

    if (/* process completion check fails */) {
        // Schedule myself for re-execution, picking up where I left off
        setTimeout(arguments.callee,0);
    }
})();

When dealing with setTimeout, it's easy to introduce race conditions. Because all timeouts are scheduled against the same timer and only one can run at a time, when two timeouts are separately scheduled, it is possible for them to execute out of intended order.

AsyncQueue supports both "chunked operations" (by specifying callback timeouts) and "iterative operations" (by specifying callback iterations or until functions). Furthermore, AsyncQueue manages the callback sequence and can therefore guarantee the execution order, so you avoid race conditions.

Exposed events

AsyncQueue is based on EventTarget and instances emit the following events throughout their lifecycle: