Queue

Getting Started

Include Dependencies

The easiest way to include the source files for Queue 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 Queue's source files and any missing dependencies when the 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 Queue.

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("queue", function(Y) { // Queue 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 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 the Queue

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

• The basics of timeout chaining
• Interacting with a Queue
  • Creating and adding to a Queue
  • Pausing and stopping a Queue
  • About Queue callbacks
  • Blocking mode for callback execution
• Exposed events

The basics of timeout chaining

Timeout chaining addresses the fact that the browser's JavaScript environment does not support multithreading. This means lengthy or iterative code execution can cause the page to stop responding until the running JavaScript process completes. This can be very detrimental to user experience. In particular, if the blocking process occurs at initial page load, the user might not see anything rendered for a few seconds or see a UI that they can't interact with.

To alleviate the situation, the function to perform the operation can be written to work in chunks. Each execution of the function will pick up where the prior execution left off, then if the work isn't yet done, the browser's setTimeout can be used to schedule another execution after a few milliseconds. The timeouts allow the browser to paint any DOM modifications the code may have made and handle any user interaction such as button clicks. In code, the basic structure of a 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.

Y.Queue builds on the basic chaining model, supporting simple chaining as well as process distribution across multiple functions that need to operate sequentially. Each callback in the Queue will yield back to the browser after execution without introducing the possibility of a race condition with the other callbacks in the same Queue.

Interacting with a Queue

Queues manage an array of callbacks that can be either simple function references or objects with specific keys. When run, each callback function is executed in turn via setTimeout. When a callback is finished, it is shifted from the array and the next is scheduled to run. It is possible to modify the Queue at any time by adding new callbacks or even modifying the configuration of existing callbacks. Modifications can be done while the Queue is running, paused, or stopped, even from within a queued callback. In addition, Queue instances fire a number of events as they run to completion.

Creating and adding to a Queue

Y.Queue can be called as a factory method or constructor. You can seed the constructor call with any number of callbacks or just add them in after instantiation. When you've built up your Queue, set it in motion by calling its run method.

YUI().use("queue", function (Y) { // Called as instance constructor var q1 = new Y.Queue(); q1.add(myfunc1,myfunc2); q1.add(myfunc3); q1.run(); // Called as factory method var q2 = Y.Queue(myfunc1,myfunc3); q2.add(myfunc3); q2.run(); });

Pausing and stopping a Queue

Queues can be paused to wait for an external process to complete, such as an XHR call via Y.io, or stopped to terminate execution and flush the Queue.

YUI().use("io","queue","json-parse", function (Y) { // Use factory style construction, seed with all callbacks, and immediately run Y.Queue( // Schedule all of these to run in order after this JavaScript thread finishes MyApp.doSomething, // The second callback will pause the Queue and send an XHR for data function () { var q = this; // for closure protection 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 Queue if successful q.run(); }, failure : function () { MyApp.showErrorStatus(); // Stop the Queue if anything goes wrong q.stop(); } }}); }, // The third callback will do partial, yielding updates until complete { fn: Y.bind(MyApp.updateUI,MyApp), until: function () { return MyApp.remainingData >= 0; } }, MyApp.doSomethingElse).run(); });

About Queue callbacks

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

fn

Required. The callback function to execute. Note, if you want this function executed from a particular context, wrap the function using Y.bind(fn, context). Default context is the Queue instance.

timeout

Milliseconds between the completion of the previous callback and the initiation of this one. This seeds the setTimeout call internally. Default is 0. Setting this to -1 will cause the callback to be executed in blocking mode.

until

A function returning true or false. The callback will not be shifted from the Queue until the function returns true. Use this to break up process intensive operations where calculating the completion criteria is not known up front or evaluating a success metric is non-trivial.

iterations

The number of times to execute the callback before shifting it from the Queue. Default is 1. This configuration is incompatible with until. If both are set, iterations will be ignored.

Blocking mode for callback execution

The main goal of the Queue is to prevent locking up the UI while a process intensive operation executes from start to finish. However, you can also use the Queue to describe an algorithm and allow external configuration to drive how certain steps of that algorithm are executed. As such, there may be times when you want to execute a couple callbacks serially in the same JavaScript thread, or to set up an iterative callback (using until or iterations) that will either execute via timeouts or all in one go depending upon an externally set configuration option.

To support this, you can set the timeout configuration of a specific callback to -1, and that callback will be executed in the same thread as the prior callback, and will continue to execute in that same thread until it is completed.

This is not a recommended setting. There are few use cases in which it is preferable to incur the overhead of callback queuing when you might just as well execute the callback functions inline in your JavaScript.

Exposed events

Event	When	Params
addCallback	Callbacks are added to the Queue.	Array of callbacks added
beforeCallback	Before each callback function is executed.	Object literal with keys fn and callback containing the function about to be executed and the callback provided to add(callback).
afterCallback	After each callback function is executed.	Object literal with keys fn and callback containing the function just executed and the callback provided to add(callback).
shiftCallback	After a callback is shifted from the Queue.	The callback provided to add(callback).
pause	After the Queue is paused.
stop	After the Queue is stopped.
end	After the last callback is finished executing. NOT when the Queue is stopped.

Support & Community