1 /*

     2 YUI 3.10.3 (build 2fb5187)

     3 Copyright 2013 Yahoo! Inc. All rights reserved.

     4 Licensed under the BSD License.

     5 http://yuilibrary.com/license/

     6 */

     7 

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

     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 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, { prefix: 'queue', 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         this.publish({

   130             'execute' : { defaultFn : this._defExecFn,    emitFacade: true },

   131             'shift'   : { defaultFn : this._defShiftFn,   emitFacade: true },

   132             'add'     : { defaultFn : this._defAddFn,     emitFacade: true },

   133             'promote' : { defaultFn : this._defPromoteFn, emitFacade: true },

   134             'remove'  : { defaultFn : this._defRemoveFn,  emitFacade: true }

   135         });

   136     },

   137 

   138     /**

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

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

   141      * the completion criteria is met.

   142      *

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

   144      *

   145      * @method next

   146      * @return {Function} the callback to execute

   147      */

   148     next : function () {

   149         var callback;

   150 

   151         while (this._q.length) {

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

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

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

   155                 callback = null;

   156             } else {

   157                 break;

   158             }

   159         }

   160 

   161         return callback || null;

   162     },

   163 

   164     /**

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

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

   167      * the queue if it is the first item.

   168      *

   169      * @method _defShiftFn

   170      * @param e {Event} The event object

   171      * @protected

   172      */

   173     _defShiftFn : function (e) {

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

   175             this._q.shift();

   176         }

   177     },

   178 

   179     /**

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

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

   182      * instance defaults, and the specified callback settings.

   183      *

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

   185      * properties for runtime modification.

   186      *

   187      * @method _prepare

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

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

   190      * @protected

   191      */

   192     _prepare: function (callback) {

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

   194             return callback;

   195         }

   196 

   197         var config = Y.merge(

   198             Queue.defaults,

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

   200             this.defaults,

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

   202             

   203             wrapper = Y.bind(function () {

   204                 if (!wrapper._running) {

   205                     wrapper.iterations--;

   206                 }

   207                 if (isFunction(wrapper.fn)) {

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

   209                                      Y.Array(wrapper.args));

   210                 }

   211             }, this);

   212             

   213         return Y.mix(wrapper, config);

   214     },

   215 

   216     /**

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

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

   219      * configured with autoContinue: false.

   220      *

   221      * @method run

   222      * @return {AsyncQueue} the AsyncQueue instance

   223      * @chainable

   224      */

   225     run : function () {

   226         var callback,

   227             cont = true;

   228 

   229         for (callback = this.next();

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

   231             callback = this.next())

   232         {

   233             cont = (callback.timeout < 0) ?

   234                 this._execute(callback) :

   235                 this._schedule(callback);

   236         }

   237 

   238         if (!callback) {

   239             /**

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

   241              * @event complete

   242              */

   243             this.fire('complete');

   244         }

   245 

   246         return this;

   247     },

   248 

   249     /**

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

   251      * whether it is appropriate to continue running.

   252      *

   253      * @method _execute

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

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

   256      * @protected

   257      */

   258     _execute : function (callback) {

   259         this._running = callback._running = true;

   260 

   261         callback.iterations--;

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

   263 

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

   265 

   266         this._running = callback._running = false;

   267 

   268         return cont;

   269     },

   270 

   271     /**

   272      * Schedules the execution of asynchronous callbacks.

   273      *

   274      * @method _schedule

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

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

   277      * @protected

   278      */

   279     _schedule : function (callback) {

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

   281             if (this._execute(callback)) {

   282                 this.run();

   283             }

   284         });

   285 

   286         return false;

   287     },

   288 

   289     /**

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

   291      *

   292      * @method isRunning

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

   294      *                   from any initiated transactions

   295      */

   296     isRunning : function () {

   297         return !!this._running;

   298     },

   299 

   300     /**

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

   302      * callback function

   303      *

   304      * @method _defExecFn

   305      * @param e {Event} the event object

   306      * @protected

   307      */

   308     _defExecFn : function (e) {

   309         e.callback();

   310     },

   311 

   312     /**

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

   314      * provided as functions or objects.

   315      *

   316      * @method add

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

   318      * @return {AsyncQueue} the AsyncQueue instance

   319      * @chainable

   320      */

   321     add : function () {

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

   323 

   324         return this;

   325     },

   326 

   327     /**

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

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

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

   331      * after phase.

   332      *

   333      * @method _defAddFn

   334      * @param e {Event} the event object

   335      * @protected

   336      */

   337     _defAddFn : function(e) {

   338         var _q = this._q,

   339             added = [];

   340 

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

   342             if (isObject(c)) {

   343                 _q.push(c);

   344                 added.push(c);

   345             }

   346         });

   347 

   348         e.added = added;

   349     },

   350 

   351     /**

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

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

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

   355      * restarted with q.run()

   356      *

   357      * @method pause

   358      * @return {AsyncQueue} the AsyncQueue instance

   359      * @chainable

   360      */

   361     pause: function () {

   362         if (isObject(this._running)) {

   363             this._running.cancel();

   364         }

   365 

   366         this._running = false;

   367 

   368         return this;

   369     },

   370 

   371     /**

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

   373      * current callback completes.

   374      *

   375      * @method stop

   376      * @return {AsyncQueue} the AsyncQueue instance

   377      * @chainable

   378      */

   379     stop : function () { 

   380         this._q = [];

   381 

   382         return this.pause();

   383     },

   384 

   385     /** 

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

   387      * callback function from getCallback.

   388      *

   389      * @method indexOf

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

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

   392      */

   393     indexOf : function (callback) {

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

   395 

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

   397             c = this._q[i];

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

   399                 return i;

   400             }

   401         }

   402 

   403         return -1;

   404     },

   405 

   406     /**

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

   408      * while the queue is running.

   409      *

   410      * @method getCallback

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

   412      * @return {Object} the callback object

   413      */

   414     getCallback : function (id) {

   415         var i = this.indexOf(id);

   416 

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

   418     },

   419 

   420     /**

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

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

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

   424      *

   425      * @method promote

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

   427      * @return {AsyncQueue} the AsyncQueue instance

   428      * @chainable

   429      */

   430     promote : function (callback) {

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

   432 

   433         if (this.isRunning()) {

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

   435                     this.fire(PROMOTE, payload);

   436                     e.detach();

   437                 }, this);

   438         } else {

   439             this.fire(PROMOTE, payload);

   440         }

   441 

   442         return this;

   443     },

   444 

   445     /**

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

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

   448      *

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

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

   451      *

   452      * @method _defPromoteFn

   453      * @param e {Event} the custom event

   454      * @protected

   455      */

   456     _defPromoteFn : function (e) {

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

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

   459 

   460         e.promoted = promoted;

   461 

   462         if (promoted) {

   463             this._q.unshift(promoted);

   464         }

   465     },

   466 

   467     /**

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

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

   470      *

   471      * @method remove

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

   473      * @return {AsyncQueue} the AsyncQueue instance

   474      * @chainable

   475      */

   476     remove : function (callback) {

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

   478 

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

   480         // current callback is complete

   481         if (this.isRunning()) {

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

   483                     this.fire(REMOVE, payload);

   484                     e.detach();

   485                 },this);

   486         } else {

   487             this.fire(REMOVE, payload);

   488         }

   489 

   490         return this;

   491     },

   492 

   493     /**

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

   495      * callback from the queue.</p>

   496      *

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

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

   499      *

   500      * @method _defRemoveFn

   501      * @param e {Event} the custom event

   502      * @protected

   503      */

   504     _defRemoveFn : function (e) {

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

   506 

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

   508     },

   509 

   510     /**

   511      * Returns the number of callbacks in the queue.

   512      *

   513      * @method size

   514      * @return {Number}

   515      */

   516     size : function () {

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

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

   519         if (!this.isRunning()) {

   520             this.next();

   521         }

   522 

   523         return this._q.length;

   524     }

   525 });

   526 

   527 

   528 

   529 }, '3.10.3', {"requires": ["event-custom"]});