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.0b1

     6 build: 1163

     7 */

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

     9 

    10 /**

    11  * <p>The Queue module adds a common data structure for FIFO operations. In its

    12  * simplest form, it is little more than an array wrapper. Additional

    13  * submodules introduce more functionality such as promotion and removal of

    14  * queued items.</p>

    15  *

    16  * <p>An AsyncQueue class is provided in the queue-run submodule.  This class

    17  * affords a mechanism to do complex sequential and iterative callback

    18  * execution across configured timeouts.

    19  *

    20  * @module queue

    21  */

    22 

    23 /**

    24  * A simple FIFO queue.  Items are added to the Queue with add(1..n items) and

    25  * removed using next().

    26  *

    27  * @module queue

    28  * @submodule queue-base

    29  * @class Queue

    30  * @param item* {MIXED} 0..n items to seed the queue

    31  */

    32 function Queue() {

    33     this._init();

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

    35 }

    36 

    37 Queue.prototype = {

    38     /**

    39      * Initialize the queue

    40      *

    41      * @method _init

    42      * @protected

    43      */

    44     _init : function () {

    45         /**

    46          * The collection of enqueued items

    47          *

    48          * @property _q

    49          * @type {Array}

    50          * @protected

    51          */

    52         this._q = [];

    53     },

    54 

    55     /**

    56      * Get the next item in the queue.

    57      *

    58      * @method next

    59      * @return {MIXED} the next item in the queue

    60      */

    61     next : function () {

    62         return this._q.shift();

    63     },

    64 

    65     /**

    66      * Add 0..n items to the end of the queue

    67      *

    68      * @method add

    69      * @param item* {MIXED} 0..n items

    70      */

    71     add : function () {

    72         Y.Array.each(Y.Array(arguments,0,true),function (fn) {

    73             this._q.push(fn);

    74         },this);

    75 

    76         return this;

    77     },

    78 

    79     /**

    80      * Returns the current number of queued items

    81      *

    82      * @method size

    83      * @return {Number}

    84      */

    85     size : function () {

    86         return this._q.length;

    87     }

    88 };

    89 

    90 Y.Queue = Queue;

    91 

    92 

    93 }, '3.0.0b1' );

    94 YUI.add('queue-run', function(Y) {

    95 

    96 /**

    97  * <p>Adds a new class AsyncQueue that is restricted to function callbacks, but

    98  * includes a host of additional features, including events, callback

    99  * iterations, and a run() method that can execute queued callbacks in order,

   100  * even across configured timeouts.</p>

   101  *

   102  * @module queue

   103  * @submodule queue-run

   104  */

   105 

   106 /**

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

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

   109  *

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

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

   112  *

   113  * <ul>

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

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

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

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

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

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

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

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

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

   123  *                        executing the next callback in the Queue after

   124  *                        the callback completes.</li>

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

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

   127  * </ul>

   128  *

   129  * @class AsyncQueue

   130  * @extends EventTarget

   131  * @constructor

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

   133  */

   134 Y.AsyncQueue = function() {

   135     this._init();

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

   137 };

   138 

   139 var Queue   = Y.AsyncQueue,

   140     EXECUTE = 'execute',

   141     SHIFT   = 'shift',

   142     PROMOTE = 'promote',

   143     REMOVE  = 'remove',

   144 

   145     isObject   = Y.Lang.isObject,

   146     isFunction = Y.Lang.isFunction;

   147 

   148 /**

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

   150  * Preconfigured defaults include:</p>

   151  *

   152  * <ul>

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

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

   155  *  <li><code>timeout</code>: -1 (synchronous operation)</li>

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

   157  * </ul>

   158  *

   159  * @property AsyncQueue.defaults

   160  * @type {Object}

   161  * @static

   162  */

   163 Queue.defaults = Y.mix({

   164     autoContinue : true,

   165     iterations   : 1,

   166     timeout      : -1,

   167     until        : function () {

   168         this.iterations |= 0;

   169         return this.iterations <= 0;

   170     }

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

   172 

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

   174     /**

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

   176      *

   177      * @property _running

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

   179      *                        return handle from Y.later for async callbacks

   180      * @protected

   181      */

   182     _running : false,

   183 

   184     /**

   185      * Initializes the AsyncQueue instance properties and events.

   186      *

   187      * @method _init

   188      * @protected

   189      */

   190     _init : function () {

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

   192 

   193         this._q = [];

   194 

   195         /** 

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

   197          * overridden are also included.

   198          *

   199          * @property defaults

   200          * @type {Object}

   201          */

   202         this.defaults = {};

   203 

   204         this._initEvents();

   205     },

   206 

   207     /**

   208      * Initializes the instance events.

   209      *

   210      * @method _initEvents

   211      * @protected

   212      */

   213     _initEvents : function () {

   214         /*

   215         this.publish({

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

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

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

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

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

   221         });

   222         */

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

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

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

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

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

   228     },

   229 

   230     /**

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

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

   233      * the completion criteria is met.

   234      *

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

   236      *

   237      * @method next

   238      * @return {Function} the callback to execute

   239      */

   240     next : function () {

   241         var callback;

   242 

   243         while (this._q.length) {

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

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

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

   247                 callback = null;

   248             } else {

   249                 break;

   250             }

   251         }

   252 

   253         return callback || null;

   254     },

   255 

   256     /**

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

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

   259      * the queue if it is the first item.

   260      *

   261      * @method _defShiftFn

   262      * @param e {Event} The event object

   263      * @protected

   264      */

   265     _defShiftFn : function (e) {

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

   267             this._q.shift();

   268         }

   269     },

   270 

   271     /**

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

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

   274      * instance defaults, and the specified callback settings.

   275      *

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

   277      * properties for runtime modification.

   278      *

   279      * @method _prepare

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

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

   282      * @protected

   283      */

   284     _prepare: function (callback) {

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

   286             return callback;

   287         }

   288 

   289         var config = Y.merge(

   290             Queue.defaults,

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

   292             this.defaults,

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

   294             

   295             wrapper = Y.bind(function () {

   296                 if (!wrapper._running) {

   297                     wrapper.iterations--;

   298                 }

   299                 if (isFunction(wrapper.fn)) {

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

   301                                      Y.Array(wrapper.args));

   302                 }

   303             }, this);

   304             

   305         return Y.mix(wrapper, config);

   306     },

   307 

   308     /**

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

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

   311      * configured with autoContinue: false.

   312      *

   313      * @method run

   314      * @return {AsyncQueue} the AsyncQueue instance

   315      * @chainable

   316      */

   317     run : function () {

   318         var callback,

   319             cont = true;

   320 

   321         for (callback = this.next();

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

   323             callback = this.next())

   324         {

   325             cont = (callback.timeout < 0) ?

   326                 this._execute(callback) :

   327                 this._schedule(callback);

   328         }

   329 

   330         if (!callback) {

   331             /**

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

   333              * @event complete

   334              */

   335             this.fire('complete');

   336         }

   337 

   338         return this;

   339     },

   340 

   341     /**

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

   343      * whether it is appropriate to continue running.

   344      *

   345      * @method _execute

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

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

   348      * @protected

   349      */

   350     _execute : function (callback) {

   351         this._running = callback._running = true;

   352 

   353         callback.iterations--;

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

   355 

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

   357 

   358         this._running = callback._running = false;

   359 

   360         return cont;

   361     },

   362 

   363     /**

   364      * Schedules the execution of asynchronous callbacks.

   365      *

   366      * @method _schedule

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

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

   369      * @protected

   370      */

   371     _schedule : function (callback) {

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

   373             if (this._execute(callback)) {

   374                 this.run();

   375             }

   376         });

   377 

   378         return false;

   379     },

   380 

   381     /**

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

   383      *

   384      * @method isRunning

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

   386      *                   from any initiated transactions

   387      */

   388     isRunning : function () {

   389         return !!this._running;

   390     },

   391 

   392     /**

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

   394      * callback function

   395      *

   396      * @method _defExecFn

   397      * @param e {Event} the event object

   398      * @protected

   399      */

   400     _defExecFn : function (e) {

   401         e.callback();

   402     },

   403 

   404     /**

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

   406      * provided as functions or objects.

   407      *

   408      * @method add

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

   410      * @return {AsyncQueue} the AsyncQueue instance

   411      * @chainable

   412      */

   413     add : function () {

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

   415 

   416         return this;

   417     },

   418 

   419     /**

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

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

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

   423      * after phase.

   424      *

   425      * @method _defAddFn

   426      * @param e {Event} the event object

   427      * @protected

   428      */

   429     _defAddFn : function(e) {

   430         var _q = this._q,

   431             added = [];

   432 

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

   434             if (isObject(c)) {

   435                 _q.push(c);

   436                 added.push(c);

   437             }

   438         });

   439 

   440         e.added = added;

   441     },

   442 

   443     /**

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

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

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

   447      * restarted with q.run()

   448      *

   449      * @method pause

   450      * @return {AsyncQueue} the AsyncQueue instance

   451      * @chainable

   452      */

   453     pause: function () {

   454         if (isObject(this._running)) {

   455             this._running.cancel();

   456         }

   457 

   458         this._running = false;

   459 

   460         return this;

   461     },

   462 

   463     /**

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

   465      * current callback completes.

   466      *

   467      * @method stop

   468      * @return {AsyncQueue} the AsyncQueue instance

   469      * @chainable

   470      */

   471     stop : function () { 

   472         this._q = [];

   473 

   474         return this.pause();

   475     },

   476 

   477     /** 

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

   479      * callback function from getCallback.

   480      *

   481      * @method indexOf

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

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

   484      */

   485     indexOf : function (callback) {

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

   487 

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

   489             c = this._q[i];

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

   491                 return i;

   492             }

   493         }

   494 

   495         return -1;

   496     },

   497 

   498     /**

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

   500      * while the queue is running.

   501      *

   502      * @method getCallback

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

   504      * @return {Object} the callback object

   505      */

   506     getCallback : function (id) {

   507         var i = this.indexOf(id);

   508 

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

   510     },

   511 

   512     /**

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

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

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

   516      *

   517      * @method promote

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

   519      * @return {AsyncQueue} the AsyncQueue instance

   520      * @chainable

   521      */

   522     promote : function (callback) {

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

   524 

   525         if (this.isRunning()) {

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

   527                     this.fire(PROMOTE, payload);

   528                     e.detach();

   529                 }, this);

   530         } else {

   531             this.fire(PROMOTE, payload);

   532         }

   533 

   534         return this;

   535     },

   536 

   537     /**

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

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

   540      *

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

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

   543      *

   544      * @method _defPromoteFn

   545      * @param e {Event} the custom event

   546      * @protected

   547      */

   548     _defPromoteFn : function (e) {

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

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

   551 

   552         e.promoted = promoted;

   553 

   554         if (promoted) {

   555             this._q.unshift(promoted);

   556         }

   557     },

   558 

   559     /**

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

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

   562      *

   563      * @method remove

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

   565      * @return {AsyncQueue} the AsyncQueue instance

   566      * @chainable

   567      */

   568     remove : function (callback) {

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

   570 

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

   572         // current callback is complete

   573         if (this.isRunning()) {

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

   575                     this.fire(REMOVE, payload);

   576                     e.detach();

   577                 },this);

   578         } else {

   579             this.fire(REMOVE, payload);

   580         }

   581 

   582         return this;

   583     },

   584 

   585     /**

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

   587      * callback from the queue.</p>

   588      *

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

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

   591      *

   592      * @method _defRemoveFn

   593      * @param e {Event} the custom event

   594      * @protected

   595      */

   596     _defRemoveFn : function (e) {

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

   598 

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

   600     },

   601 

   602     /**

   603      * Returns the number of callbacks in the queue.

   604      *

   605      * @method size

   606      * @return {Number}

   607      */

   608     size : function () {

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

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

   611         if (!this.isRunning()) {

   612             this.next();

   613         }

   614 

   615         return this._q.length;

   616     }

   617 });

   618 

   619 

   620 

   621 }, '3.0.0b1' ,{requires:['queue-base','oop','event-custom']});

   622 

   623 

   624 YUI.add('queue', function(Y){}, '3.0.0b1' ,{use:['queue-base', 'queue-run']});

   625