YUI 3: AsyncQueue

Getting Started

Include Dependencies

The easiest way to include the source files for AsyncQueue and its dependencies is to add the YUI seed file to your page, using the following script tag, and allow the YUI instance to download any additional files which may be required:

<!-- YUI Seed --> <script src="http://yui.yahooapis.com/3.0.0/build/yui/yui-min.js"></script>

The YUI instance will automatically pull down AsyncQueue's source files and any missing dependencies when the async-queue module is used. This helps you avoid having to manually manage the list of files needed on your page to support multiple components while also optimizing your initial page weight by loading files only when they are required.

If you do want to include file dependencies manually on your page, the YUI Dependency Configurator can be used to determine the list of files you need to include in order to use AsyncQueue.

The YUI Instance

Once you have the YUI seed file on your page (yui-min.js), you can create a new YUI instance for your application to use and populate it with the modules you need, specified as the first set of arguments to the use method:

// Create new YUI instance, and populate it with the required modules YUI().use("async-queue", function(Y) { // AsyncQueue available, and ready for use. });

The last argument passed to use is a callback function. The callback function will be invoked as soon as the YUI instance is done downloading any required files missing from your page. Once those files are loaded, your local YUI instance will be supplemented with the classes which make up the async-queue module and any modules it depends on. A reference to the populated YUI instance (Y) is passed back to your callback function. Within your callback, then, you can start writing your application code based on your own custom instance of YUI.

For more information on creating instances of YUI and the use method, see the YUI Global object documentation.

Using AsyncQueue

This section describes how to use AsyncQueue in further detail. It contains these subsections:

• Creating and interacting with an AsyncQueue
• Pausing and stopping
• About AsyncQueue callbacks
• Synchronous mode for callback execution
• The basics of timeout chaining
• Exposed events

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(), each callback is executed in turn either synchronously, or via setTimeout, depending on the configuration of the callback or 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:

property	description	default
fn	Required. The callback function to execute.	(none)
context	The context from which to execute the callback function.	The AsyncQueue instance
args	Array of arguments that will be passed as individual args to the callback function.	(none)
timeout	Millisecond delay before the execution of each execution of this callback. Set to -1 to trigger synchronous execution.	10
iterations	The number of times to execute this callback before shifting it from the queue.	1
until	A function that will return true when the current callback can be shifted from the queue.	a function that tests against iterations
id	Name given to this callback for ease of reference.	(none)
autoContinue	Set to false to automatically pause() after this callback.	true

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. This can obviously be very detrimental to user experience.

To address this, the operation can be split into chunks and setTimeout used to yield control back to other operations between them, such as browser reflows to display DOM modifications. 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 is 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 no race conditions.

Exposed events

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

Event	When	Event payload
add	Callbacks are added to the AsyncQueue.	{ callbacks: (Array of callbacks added) }
promote	A callback is promoted.	{ callback : (callback) }
remove	A callback is removed.	{ callback : (callback) }
execute	A callback is executed.	{ callback : (callback) }
shift	A callback is shifted from the AsyncQueue.	{ callback : (callback) }
complete	After the last callback is finished executing. NOT fired after stop().	(none)

Support & Community