1 /*

     2 Copyright (c) 2009, Yahoo! Inc. All rights reserved.

     3 Code licensed under the BSD License:

     4 http://developer.yahoo.net/yui/license.txt

     5 version: 3.0.0

     6 build: 1549

     7 */

     8 YUI.add('async-queue', function(Y) {

     9 

    10 /**

    11  * <p>AsyncQueue allows you create a chain of function callbacks executed

    12  * via setTimeout (or synchronously) that are guaranteed to run in order.

    13  * Items in the queue can be promoted or removed.  Start or resume the

    14  * execution chain with run().  pause() to temporarily delay execution, or

    15  * stop() to halt and clear the queue.</p>

    16  *

    17  * @module async-queue

    18  */

    19 

    20 /**

    21  * <p>A specialized queue class that supports scheduling callbacks to execute

    22  * sequentially, iteratively, even asynchronously.</p>

    23  *

    24  * <p>Callbacks can be function refs or objects with the following keys.  Only

    25  * the <code>fn</code> key is required.</p>

    26  *

    27  * <ul>

    28  * <li><code>fn</code> -- The callback function</li>

    29  * <li><code>context</code> -- The execution context for the callbackFn.</li>

    30  * <li><code>args</code> -- Arguments to pass to callbackFn.</li>

    31  * <li><code>timeout</code> -- Millisecond delay before executing callbackFn.

    32  *                     (Applies to each iterative execution of callback)</li>

    33  * <li><code>iterations</code> -- Number of times to repeat the callback.

    34  * <li><code>until</code> -- Repeat the callback until this function returns

    35  *                         true.  This setting trumps iterations.</li>

    36  * <li><code>autoContinue</code> -- Set to false to prevent the AsyncQueue from

    37  *                        executing the next callback in the Queue after

    38  *                        the callback completes.</li>

    39  * <li><code>id</code> -- Name that can be used to get, promote, get the

    40  *                        indexOf, or delete this callback.</li>

    41  * </ul>

    42  *

    43  * @class AsyncQueue

    44  * @extends EventTarget

    45  * @constructor

    46  * @param callback* {Function|Object} 0..n callbacks to seed the queue

    47  */

    48 Y.AsyncQueue = function() {

    49     this._init();

    50     this.add.apply(this, arguments);

    51 };

    52 

    53 var Queue   = Y.AsyncQueue,

    54     EXECUTE = 'execute',

    55     SHIFT   = 'shift',

    56     PROMOTE = 'promote',

    57     REMOVE  = 'remove',

    58 

    59     isObject   = Y.Lang.isObject,

    60     isFunction = Y.Lang.isFunction;

    61 

    62 /**

    63  * <p>Static default values used to populate callback configuration properties.

    64  * Preconfigured defaults include:</p>

    65  *

    66  * <ul>

    67  *  <li><code>autoContinue</code>: <code>true</code></li>

    68  *  <li><code>iterations</code>: 1</li>

    69  *  <li><code>timeout</code>: 10 (10ms between callbacks)</li>

    70  *  <li><code>until</code>: (function to run until iterations &lt;= 0)</li>

    71  * </ul>

    72  *

    73  * @property AsyncQueue.defaults

    74  * @type {Object}

    75  * @static

    76  */

    77 Queue.defaults = Y.mix({

    78     autoContinue : true,

    79     iterations   : 1,

    80     timeout      : 10,

    81     until        : function () {

    82         this.iterations |= 0;

    83         return this.iterations <= 0;

    84     }

    85 }, Y.config.queueDefaults || {});

    86 

    87 Y.extend(Queue, Y.EventTarget, {

    88     /**

    89      * Used to indicate the queue is currently executing a callback.

    90      *

    91      * @property _running

    92      * @type {Boolean|Object} true for synchronous callback execution, the

    93      *                        return handle from Y.later for async callbacks.

    94      *                        Otherwise false.

    95      * @protected

    96      */

    97     _running : false,

    98 

    99     /**

   100      * Initializes the AsyncQueue instance properties and events.

   101      *

   102      * @method _init

   103      * @protected

   104      */

   105     _init : function () {

   106         Y.EventTarget.call(this, { emitFacade: true });

   107 

   108         this._q = [];

   109 

   110         /** 

   111          * Callback defaults for this instance.  Static defaults that are not

   112          * overridden are also included.

   113          *

   114          * @property defaults

   115          * @type {Object}

   116          */

   117         this.defaults = {};

   118 

   119         this._initEvents();

   120     },

   121 

   122     /**

   123      * Initializes the instance events.

   124      *

   125      * @method _initEvents

   126      * @protected

   127      */

   128     _initEvents : function () {

   129         /*

   130         this.publish({

   131             'execute' : { defaultFn : this._defExecFn },

   132             'shift'   : { defaultFn : this._defShiftFn },

   133             'add'     : { defaultFn : this._defAddFn },

   134             'promote' : { defaultFn : this._defPromoteFn },

   135             'remove'  : { defaultFn : this._defRemoveFn }

   136         });

   137         */

   138         this.publish('execute' , { defaultFn : this._defExecFn, emitFacade: true });

   139         this.publish('shift'   , { defaultFn : this._defShiftFn, emitFacade: true });

   140         this.publish('add'     , { defaultFn : this._defAddFn, emitFacade: true });

   141         this.publish('promote' , { defaultFn : this._defPromoteFn, emitFacade: true });

   142         this.publish('remove'  , { defaultFn : this._defRemoveFn, emitFacade: true });

   143     },

   144 

   145     /**

   146      * Returns the next callback needing execution.  If a callback is

   147      * configured to repeat via iterations or until, it will be returned until

   148      * the completion criteria is met.

   149      *

   150      * When the queue is empty, null is returned.

   151      *

   152      * @method next

   153      * @return {Function} the callback to execute

   154      */

   155     next : function () {

   156         var callback;

   157 

   158         while (this._q.length) {

   159             callback = this._q[0] = this._prepare(this._q[0]);

   160             if (callback && callback.until()) {

   161                 this.fire(SHIFT, { callback: callback });

   162                 callback = null;

   163             } else {

   164                 break;

   165             }

   166         }

   167 

   168         return callback || null;

   169     },

   170 

   171     /**

   172      * Default functionality for the "shift" event.  Shifts the

   173      * callback stored in the event object's <em>callback</em> property from

   174      * the queue if it is the first item.

   175      *

   176      * @method _defShiftFn

   177      * @param e {Event} The event object

   178      * @protected

   179      */

   180     _defShiftFn : function (e) {

   181         if (this.indexOf(e.callback) === 0) {

   182             this._q.shift();

   183         }

   184     },

   185 

   186     /**

   187      * Creates a wrapper function to execute the callback using the aggregated 

   188      * configuration generated by combining the static AsyncQueue.defaults, the

   189      * instance defaults, and the specified callback settings.

   190      *

   191      * The wrapper function is decorated with the callback configuration as

   192      * properties for runtime modification.

   193      *

   194      * @method _prepare

   195      * @param callback {Object|Function} the raw callback

   196      * @return {Function} a decorated function wrapper to execute the callback

   197      * @protected

   198      */

   199     _prepare: function (callback) {

   200         if (isFunction(callback) && callback._prepared) {

   201             return callback;

   202         }

   203 

   204         var config = Y.merge(

   205             Queue.defaults,

   206             { context : this, args: [], _prepared: true },

   207             this.defaults,

   208             (isFunction(callback) ? { fn: callback } : callback)),

   209             

   210             wrapper = Y.bind(function () {

   211                 if (!wrapper._running) {

   212                     wrapper.iterations--;

   213                 }

   214                 if (isFunction(wrapper.fn)) {

   215                     wrapper.fn.apply(wrapper.context || Y,

   216                                      Y.Array(wrapper.args));

   217                 }

   218             }, this);

   219             

   220         return Y.mix(wrapper, config);

   221     },

   222 

   223     /**

   224      * Sets the queue in motion.  All queued callbacks will be executed in

   225      * order unless pause() or stop() is called or if one of the callbacks is

   226      * configured with autoContinue: false.

   227      *

   228      * @method run

   229      * @return {AsyncQueue} the AsyncQueue instance

   230      * @chainable

   231      */

   232     run : function () {

   233         var callback,

   234             cont = true;

   235 

   236         for (callback = this.next();

   237             cont && callback && !this.isRunning();

   238             callback = this.next())

   239         {

   240             cont = (callback.timeout < 0) ?

   241                 this._execute(callback) :

   242                 this._schedule(callback);

   243         }

   244 

   245         if (!callback) {

   246             /**

   247              * Event fired after the last queued callback is executed.

   248              * @event complete

   249              */

   250             this.fire('complete');

   251         }

   252 

   253         return this;

   254     },

   255 

   256     /**

   257      * Handles the execution of callbacks. Returns a boolean indicating

   258      * whether it is appropriate to continue running.

   259      *

   260      * @method _execute

   261      * @param callback {Object} the callback object to execute

   262      * @return {Boolean} whether the run loop should continue

   263      * @protected

   264      */

   265     _execute : function (callback) {

   266         this._running = callback._running = true;

   267 

   268         callback.iterations--;

   269         this.fire(EXECUTE, { callback: callback });

   270 

   271         var cont = this._running && callback.autoContinue;

   272 

   273         this._running = callback._running = false;

   274 

   275         return cont;

   276     },

   277 

   278     /**

   279      * Schedules the execution of asynchronous callbacks.

   280      *

   281      * @method _schedule

   282      * @param callback {Object} the callback object to execute

   283      * @return {Boolean} whether the run loop should continue

   284      * @protected

   285      */

   286     _schedule : function (callback) {

   287         this._running = Y.later(callback.timeout, this, function () {

   288             if (this._execute(callback)) {

   289                 this.run();

   290             }

   291         });

   292 

   293         return false;

   294     },

   295 

   296     /**

   297      * Determines if the queue is waiting for a callback to complete execution.

   298      *

   299      * @method isRunning

   300      * @return {Boolean} true if queue is waiting for a 

   301      *                   from any initiated transactions

   302      */

   303     isRunning : function () {

   304         return !!this._running;

   305     },

   306 

   307     /**

   308      * Default functionality for the "execute" event.  Executes the

   309      * callback function

   310      *

   311      * @method _defExecFn

   312      * @param e {Event} the event object

   313      * @protected

   314      */

   315     _defExecFn : function (e) {

   316         e.callback();

   317     },

   318 

   319     /**

   320      * Add any number of callbacks to the end of the queue. Callbacks may be

   321      * provided as functions or objects.

   322      *

   323      * @method add

   324      * @param callback* {Function|Object} 0..n callbacks

   325      * @return {AsyncQueue} the AsyncQueue instance

   326      * @chainable

   327      */

   328     add : function () {

   329         this.fire('add', { callbacks: Y.Array(arguments,0,true) });

   330 

   331         return this;

   332     },

   333 

   334     /**

   335      * Default functionality for the "add" event.  Adds the callbacks

   336      * in the event facade to the queue. Callbacks successfully added to the

   337      * queue are present in the event's <code>added</code> property in the

   338      * after phase.

   339      *

   340      * @method _defAddFn

   341      * @param e {Event} the event object

   342      * @protected

   343      */

   344     _defAddFn : function(e) {

   345         var _q = this._q,

   346             added = [];

   347 

   348         Y.Array.each(e.callbacks, function (c) {

   349             if (isObject(c)) {

   350                 _q.push(c);

   351                 added.push(c);

   352             }

   353         });

   354 

   355         e.added = added;

   356     },

   357 

   358     /**

   359      * Pause the execution of the queue after the execution of the current

   360      * callback completes.  If called from code outside of a queued callback,

   361      * clears the timeout for the pending callback. Paused queue can be

   362      * restarted with q.run()

   363      *

   364      * @method pause

   365      * @return {AsyncQueue} the AsyncQueue instance

   366      * @chainable

   367      */

   368     pause: function () {

   369         if (isObject(this._running)) {

   370             this._running.cancel();

   371         }

   372 

   373         this._running = false;

   374 

   375         return this;

   376     },

   377 

   378     /**

   379      * Stop and clear the queue after the current execution of the

   380      * current callback completes.

   381      *

   382      * @method stop

   383      * @return {AsyncQueue} the AsyncQueue instance

   384      * @chainable

   385      */

   386     stop : function () { 

   387         this._q = [];

   388 

   389         return this.pause();

   390     },

   391 

   392     /** 

   393      * Returns the current index of a callback.  Pass in either the id or

   394      * callback function from getCallback.

   395      *

   396      * @method indexOf

   397      * @param callback {String|Function} the callback or its specified id

   398      * @return {Number} index of the callback or -1 if not found

   399      */

   400     indexOf : function (callback) {

   401         var i = 0, len = this._q.length, c;

   402 

   403         for (; i < len; ++i) {

   404             c = this._q[i];

   405             if (c === callback || c.id === callback) {

   406                 return i;

   407             }

   408         }

   409 

   410         return -1;

   411     },

   412 

   413     /**

   414      * Retrieve a callback by its id.  Useful to modify the configuration

   415      * while the queue is running.

   416      *

   417      * @method getCallback

   418      * @param id {String} the id assigned to the callback

   419      * @return {Object} the callback object

   420      */

   421     getCallback : function (id) {

   422         var i = this.indexOf(id);

   423 

   424         return (i > -1) ? this._q[i] : null;

   425     },

   426 

   427     /**

   428      * Promotes the named callback to the top of the queue. If a callback is

   429      * currently executing or looping (via until or iterations), the promotion

   430      * is scheduled to occur after the current callback has completed.

   431      *

   432      * @method promote

   433      * @param callback {String|Object} the callback object or a callback's id

   434      * @return {AsyncQueue} the AsyncQueue instance

   435      * @chainable

   436      */

   437     promote : function (callback) {

   438         var payload = { callback : callback },e;

   439 

   440         if (this.isRunning()) {

   441             e = this.after(SHIFT, function () {

   442                     this.fire(PROMOTE, payload);

   443                     e.detach();

   444                 }, this);

   445         } else {

   446             this.fire(PROMOTE, payload);

   447         }

   448 

   449         return this;

   450     },

   451 

   452     /**

   453      * <p>Default functionality for the &quot;promote&quot; event.  Promotes the

   454      * named callback to the head of the queue.</p>

   455      *

   456      * <p>The event object will contain a property &quot;callback&quot;, which

   457      * holds the id of a callback or the callback object itself.</p>

   458      *

   459      * @method _defPromoteFn

   460      * @param e {Event} the custom event

   461      * @protected

   462      */

   463     _defPromoteFn : function (e) {

   464         var i = this.indexOf(e.callback),

   465             promoted = (i > -1) ? this._q.splice(i,1)[0] : null;

   466 

   467         e.promoted = promoted;

   468 

   469         if (promoted) {

   470             this._q.unshift(promoted);

   471         }

   472     },

   473 

   474     /**

   475      * Removes the callback from the queue.  If the queue is active, the

   476      * removal is scheduled to occur after the current callback has completed.

   477      *

   478      * @method remove

   479      * @param callback {String|Object} the callback object or a callback's id

   480      * @return {AsyncQueue} the AsyncQueue instance

   481      * @chainable

   482      */

   483     remove : function (callback) {

   484         var payload = { callback : callback },e;

   485 

   486         // Can't return the removed callback because of the deferral until

   487         // current callback is complete

   488         if (this.isRunning()) {

   489             e = this.after(SHIFT, function () {

   490                     this.fire(REMOVE, payload);

   491                     e.detach();

   492                 },this);

   493         } else {

   494             this.fire(REMOVE, payload);

   495         }

   496 

   497         return this;

   498     },

   499 

   500     /**

   501      * <p>Default functionality for the &quot;remove&quot; event.  Removes the

   502      * callback from the queue.</p>

   503      *

   504      * <p>The event object will contain a property &quot;callback&quot;, which

   505      * holds the id of a callback or the callback object itself.</p>

   506      *

   507      * @method _defRemoveFn

   508      * @param e {Event} the custom event

   509      * @protected

   510      */

   511     _defRemoveFn : function (e) {

   512         var i = this.indexOf(e.callback);

   513 

   514         e.removed = (i > -1) ? this._q.splice(i,1)[0] : null;

   515     },

   516 

   517     /**

   518      * Returns the number of callbacks in the queue.

   519      *

   520      * @method size

   521      * @return {Number}

   522      */

   523     size : function () {

   524         // next() flushes callbacks that have met their until() criteria and

   525         // therefore shouldn't count since they wouldn't execute anyway.

   526         if (!this.isRunning()) {

   527             this.next();

   528         }

   529 

   530         return this._q.length;

   531     }

   532 });

   533 

   534 

   535 

   536 }, '3.0.0' ,{requires:['event-custom']});