@canonical/yui 3.18.2-pre

package/build/async-queue/async-queue-debug.js

@@ -0,0 +1,554 @@
+YUI.add('async-queue', function (Y, NAME) {
+
+/**
+ * <p>AsyncQueue allows you create a chain of function callbacks executed
+ * via setTimeout (or synchronously) that are guaranteed to run in order.
+ * Items in the queue can be promoted or removed.  Start or resume the
+ * execution chain with run().  pause() to temporarily delay execution, or
+ * stop() to halt and clear the queue.</p>
+ *
+ * @module async-queue
+ */
+
+/**
+ * <p>A specialized queue class that supports scheduling callbacks to execute
+ * sequentially, iteratively, even asynchronously.</p>
+ *
+ * <p>Callbacks can be function refs or objects with the following keys.  Only
+ * the <code>fn</code> key is required.</p>
+ *
+ * <ul>
+ * <li><code>fn</code> -- The callback function</li>
+ * <li><code>context</code> -- The execution context for the callbackFn.</li>
+ * <li><code>args</code> -- Arguments to pass to callbackFn.</li>
+ * <li><code>timeout</code> -- Millisecond delay before executing callbackFn.
+ *                     (Applies to each iterative execution of callback)</li>
+ * <li><code>iterations</code> -- Number of times to repeat the callback.
+ * <li><code>until</code> -- Repeat the callback until this function returns
+ *                         true.  This setting trumps iterations.</li>
+ * <li><code>autoContinue</code> -- Set to false to prevent the AsyncQueue from
+ *                        executing the next callback in the Queue after
+ *                        the callback completes.</li>
+ * <li><code>id</code> -- Name that can be used to get, promote, get the
+ *                        indexOf, or delete this callback.</li>
+ * </ul>
+ *
+ * @class AsyncQueue
+ * @extends EventTarget
+ * @constructor
+ * @param callback* {Function|Object} 0..n callbacks to seed the queue
+ */
+Y.AsyncQueue = function() {
+    this._init();
+    this.add.apply(this, arguments);
+};
+
+var Queue   = Y.AsyncQueue,
+    EXECUTE = 'execute',
+    SHIFT   = 'shift',
+    PROMOTE = 'promote',
+    REMOVE  = 'remove',
+
+    isObject   = Y.Lang.isObject,
+    isFunction = Y.Lang.isFunction;
+
+/**
+ * <p>Static default values used to populate callback configuration properties.
+ * Preconfigured defaults include:</p>
+ *
+ * <ul>
+ *  <li><code>autoContinue</code>: <code>true</code></li>
+ *  <li><code>iterations</code>: 1</li>
+ *  <li><code>timeout</code>: 10 (10ms between callbacks)</li>
+ *  <li><code>until</code>: (function to run until iterations &lt;= 0)</li>
+ * </ul>
+ *
+ * @property defaults
+ * @type {Object}
+ * @static
+ */
+Queue.defaults = Y.mix({
+    autoContinue : true,
+    iterations   : 1,
+    timeout      : 10,
+    until        : function () {
+        this.iterations |= 0;
+        return this.iterations <= 0;
+    }
+}, Y.config.queueDefaults || {});
+
+Y.extend(Queue, Y.EventTarget, {
+    /**
+     * Used to indicate the queue is currently executing a callback.
+     *
+     * @property _running
+     * @type {Boolean|Object} true for synchronous callback execution, the
+     *                        return handle from Y.later for async callbacks.
+     *                        Otherwise false.
+     * @protected
+     */
+    _running : false,
+
+    /**
+     * Initializes the AsyncQueue instance properties and events.
+     *
+     * @method _init
+     * @protected
+     */
+    _init : function () {
+        Y.EventTarget.call(this, { prefix: 'queue', emitFacade: true });
+
+        this._q = [];
+
+        /**
+         * Callback defaults for this instance.  Static defaults that are not
+         * overridden are also included.
+         *
+         * @property defaults
+         * @type {Object}
+         */
+        this.defaults = {};
+
+        this._initEvents();
+    },
+
+    /**
+     * Initializes the instance events.
+     *
+     * @method _initEvents
+     * @protected
+     */
+    _initEvents : function () {
+        this.publish({
+            'execute' : { defaultFn : this._defExecFn,    emitFacade: true },
+            'shift'   : { defaultFn : this._defShiftFn,   emitFacade: true },
+            'add'     : { defaultFn : this._defAddFn,     emitFacade: true },
+            'promote' : { defaultFn : this._defPromoteFn, emitFacade: true },
+            'remove'  : { defaultFn : this._defRemoveFn,  emitFacade: true }
+        });
+    },
+
+    /**
+     * Returns the next callback needing execution.  If a callback is
+     * configured to repeat via iterations or until, it will be returned until
+     * the completion criteria is met.
+     *
+     * When the queue is empty, null is returned.
+     *
+     * @method next
+     * @return {Function} the callback to execute
+     */
+    next : function () {
+        var callback;
+
+        while (this._q.length) {
+            callback = this._q[0] = this._prepare(this._q[0]);
+            if (callback && callback.until()) {
+                this.fire(SHIFT, { callback: callback });
+                callback = null;
+            } else {
+                break;
+            }
+        }
+
+        return callback || null;
+    },
+
+    /**
+     * Default functionality for the &quot;shift&quot; event.  Shifts the
+     * callback stored in the event object's <em>callback</em> property from
+     * the queue if it is the first item.
+     *
+     * @method _defShiftFn
+     * @param e {Event} The event object
+     * @protected
+     */
+    _defShiftFn : function (e) {
+        if (this.indexOf(e.callback) === 0) {
+            this._q.shift();
+        }
+    },
+
+    /**
+     * Creates a wrapper function to execute the callback using the aggregated
+     * configuration generated by combining the static AsyncQueue.defaults, the
+     * instance defaults, and the specified callback settings.
+     *
+     * The wrapper function is decorated with the callback configuration as
+     * properties for runtime modification.
+     *
+     * @method _prepare
+     * @param callback {Object|Function} the raw callback
+     * @return {Function} a decorated function wrapper to execute the callback
+     * @protected
+     */
+    _prepare: function (callback) {
+        if (isFunction(callback) && callback._prepared) {
+            return callback;
+        }
+
+        var config = Y.merge(
+            Queue.defaults,
+            { context : this, args: [], _prepared: true },
+            this.defaults,
+            (isFunction(callback) ? { fn: callback } : callback)),
+
+            wrapper = Y.bind(function () {
+                if (!wrapper._running) {
+                    wrapper.iterations--;
+                }
+                if (isFunction(wrapper.fn)) {
+                    wrapper.fn.apply(wrapper.context || Y,
+                                     Y.Array(wrapper.args));
+                }
+            }, this);
+
+        return Y.mix(wrapper, config);
+    },
+
+    /**
+     * Sets the queue in motion.  All queued callbacks will be executed in
+     * order unless pause() or stop() is called or if one of the callbacks is
+     * configured with autoContinue: false.
+     *
+     * @method run
+     * @return {AsyncQueue} the AsyncQueue instance
+     * @chainable
+     */
+    run : function () {
+        var callback,
+            cont = true;
+
+        if (this._executing) {
+            this._running = true;
+            return this;
+        }
+
+        for (callback = this.next();
+            callback && !this.isRunning();
+            callback = this.next())
+        {
+            cont = (callback.timeout < 0) ?
+                this._execute(callback) :
+                this._schedule(callback);
+
+            // Break to avoid an extra call to next (final-expression of the
+            // 'for' loop), because the until function of the next callback
+            // in the queue may return a wrong result if it depends on the
+            // not-yet-finished work of the previous callback.
+            if (!cont) {
+                break;
+            }
+        }
+
+        if (!callback) {
+            /**
+             * Event fired when there is no remaining callback in the running queue. Also fired after stop().
+             * @event complete
+             */
+            this.fire('complete');
+        }
+
+        return this;
+    },
+
+    /**
+     * Handles the execution of callbacks. Returns a boolean indicating
+     * whether it is appropriate to continue running.
+     *
+     * @method _execute
+     * @param callback {Object} the callback object to execute
+     * @return {Boolean} whether the run loop should continue
+     * @protected
+     */
+    _execute : function (callback) {
+
+        this._running   = callback._running = true;
+        this._executing = callback;
+
+        callback.iterations--;
+        this.fire(EXECUTE, { callback: callback });
+
+        var cont = this._running && callback.autoContinue;
+
+        this._running   = callback._running = false;
+        this._executing = false;
+
+        return cont;
+    },
+
+    /**
+     * Schedules the execution of asynchronous callbacks.
+     *
+     * @method _schedule
+     * @param callback {Object} the callback object to execute
+     * @return {Boolean} whether the run loop should continue
+     * @protected
+     */
+    _schedule : function (callback) {
+        this._running = Y.later(callback.timeout, this, function () {
+            if (this._execute(callback)) {
+                this.run();
+            }
+        });
+
+        return false;
+    },
+
+    /**
+     * Determines if the queue is waiting for a callback to complete execution.
+     *
+     * @method isRunning
+     * @return {Boolean} true if queue is waiting for a
+     *                   from any initiated transactions
+     */
+    isRunning : function () {
+        return !!this._running;
+    },
+
+    /**
+     * Default functionality for the &quot;execute&quot; event.  Executes the
+     * callback function
+     *
+     * @method _defExecFn
+     * @param e {Event} the event object
+     * @protected
+     */
+    _defExecFn : function (e) {
+        e.callback();
+    },
+
+    /**
+     * Add any number of callbacks to the end of the queue. Callbacks may be
+     * provided as functions or objects.
+     *
+     * @method add
+     * @param callback* {Function|Object} 0..n callbacks
+     * @return {AsyncQueue} the AsyncQueue instance
+     * @chainable
+     */
+    add : function () {
+        this.fire('add', { callbacks: Y.Array(arguments,0,true) });
+
+        return this;
+    },
+
+    /**
+     * Default functionality for the &quot;add&quot; event.  Adds the callbacks
+     * in the event facade to the queue. Callbacks successfully added to the
+     * queue are present in the event's <code>added</code> property in the
+     * after phase.
+     *
+     * @method _defAddFn
+     * @param e {Event} the event object
+     * @protected
+     */
+    _defAddFn : function(e) {
+        var _q = this._q,
+            added = [];
+
+        Y.Array.each(e.callbacks, function (c) {
+            if (isObject(c)) {
+                _q.push(c);
+                added.push(c);
+            }
+        });
+
+        e.added = added;
+    },
+
+    /**
+     * Pause the execution of the queue after the execution of the current
+     * callback completes.  If called from code outside of a queued callback,
+     * clears the timeout for the pending callback. Paused queue can be
+     * restarted with q.run()
+     *
+     * @method pause
+     * @return {AsyncQueue} the AsyncQueue instance
+     * @chainable
+     */
+    pause: function () {
+        if (this._running && isObject(this._running)) {
+            this._running.cancel();
+        }
+
+        this._running = false;
+
+        return this;
+    },
+
+    /**
+     * Stop and clear the queue after the current execution of the
+     * current callback completes.
+     *
+     * @method stop
+     * @return {AsyncQueue} the AsyncQueue instance
+     * @chainable
+     */
+    stop : function () {
+
+        this._q = [];
+
+        if (this._running && isObject(this._running)) {
+            this._running.cancel();
+            this._running = false;
+        }
+        // otherwise don't systematically set this._running to false, because if
+        // stop has been called from inside a queued callback, the _execute method
+        // currenty running needs to call run() one more time for the 'complete'
+        // event to be fired.
+
+        // if stop is called from outside a callback, we need to explicitely call
+        // run() once again to fire the 'complete' event.
+        if (!this._executing) {
+            this.run();
+        }
+
+        return this;
+    },
+
+    /**
+     * Returns the current index of a callback.  Pass in either the id or
+     * callback function from getCallback.
+     *
+     * @method indexOf
+     * @param callback {String|Function} the callback or its specified id
+     * @return {Number} index of the callback or -1 if not found
+     */
+    indexOf : function (callback) {
+        var i = 0, len = this._q.length, c;
+
+        for (; i < len; ++i) {
+            c = this._q[i];
+            if (c === callback || c.id === callback) {
+                return i;
+            }
+        }
+
+        return -1;
+    },
+
+    /**
+     * Retrieve a callback by its id.  Useful to modify the configuration
+     * while the queue is running.
+     *
+     * @method getCallback
+     * @param id {String} the id assigned to the callback
+     * @return {Object} the callback object
+     */
+    getCallback : function (id) {
+        var i = this.indexOf(id);
+
+        return (i > -1) ? this._q[i] : null;
+    },
+
+    /**
+     * Promotes the named callback to the top of the queue. If a callback is
+     * currently executing or looping (via until or iterations), the promotion
+     * is scheduled to occur after the current callback has completed.
+     *
+     * @method promote
+     * @param callback {String|Object} the callback object or a callback's id
+     * @return {AsyncQueue} the AsyncQueue instance
+     * @chainable
+     */
+    promote : function (callback) {
+        var payload = { callback : callback },e;
+
+        if (this.isRunning()) {
+            e = this.after(SHIFT, function () {
+                    this.fire(PROMOTE, payload);
+                    e.detach();
+                }, this);
+        } else {
+            this.fire(PROMOTE, payload);
+        }
+
+        return this;
+    },
+
+    /**
+     * <p>Default functionality for the &quot;promote&quot; event.  Promotes the
+     * named callback to the head of the queue.</p>
+     *
+     * <p>The event object will contain a property &quot;callback&quot;, which
+     * holds the id of a callback or the callback object itself.</p>
+     *
+     * @method _defPromoteFn
+     * @param e {Event} the custom event
+     * @protected
+     */
+    _defPromoteFn : function (e) {
+        var i = this.indexOf(e.callback),
+            promoted = (i > -1) ? this._q.splice(i,1)[0] : null;
+
+        e.promoted = promoted;
+
+        if (promoted) {
+            this._q.unshift(promoted);
+        }
+    },
+
+    /**
+     * Removes the callback from the queue.  If the queue is active, the
+     * removal is scheduled to occur after the current callback has completed.
+     *
+     * @method remove
+     * @param callback {String|Object} the callback object or a callback's id
+     * @return {AsyncQueue} the AsyncQueue instance
+     * @chainable
+     */
+    remove : function (callback) {
+        var payload = { callback : callback },e;
+
+        // Can't return the removed callback because of the deferral until
+        // current callback is complete
+        if (this.isRunning()) {
+            e = this.after(SHIFT, function () {
+                    this.fire(REMOVE, payload);
+                    e.detach();
+                },this);
+        } else {
+            this.fire(REMOVE, payload);
+        }
+
+        return this;
+    },
+
+    /**
+     * <p>Default functionality for the &quot;remove&quot; event.  Removes the
+     * callback from the queue.</p>
+     *
+     * <p>The event object will contain a property &quot;callback&quot;, which
+     * holds the id of a callback or the callback object itself.</p>
+     *
+     * @method _defRemoveFn
+     * @param e {Event} the custom event
+     * @protected
+     */
+    _defRemoveFn : function (e) {
+        var i = this.indexOf(e.callback);
+
+        e.removed = (i > -1) ? this._q.splice(i,1)[0] : null;
+    },
+
+    /**
+     * Returns the number of callbacks in the queue.
+     *
+     * @method size
+     * @return {Number}
+     */
+    size : function () {
+        // next() flushes callbacks that have met their until() criteria and
+        // therefore shouldn't count since they wouldn't execute anyway.
+        if (!this.isRunning()) {
+            this.next();
+        }
+
+        return this._q.length;
+    }
+});
+
+
+
+}, '@VERSION@', {"requires": ["event-custom"]});

package/build/async-queue/async-queue-min.js

@@ -0,0 +1 @@
+YUI.add("async-queue",function(e,t){e.AsyncQueue=function(){this._init(),this.add.apply(this,arguments)};var n=e.AsyncQueue,r="execute",i="shift",s="promote",o="remove",u=e.Lang.isObject,a=e.Lang.isFunction;n.defaults=e.mix({autoContinue:!0,iterations:1,timeout:10,until:function(){return this.iterations|=0,this.iterations<=0}},e.config.queueDefaults||{}),e.extend(n,e.EventTarget,{_running:!1,_init:function(){e.EventTarget.call(this,{prefix:"queue",emitFacade:!0}),this._q=[],this.defaults={},this._initEvents()},_initEvents:function(){this.publish({execute:{defaultFn:this._defExecFn,emitFacade:!0},shift:{defaultFn:this._defShiftFn,emitFacade:!0},add:{defaultFn:this._defAddFn,emitFacade:!0},promote:{defaultFn:this._defPromoteFn,emitFacade:!0},remove:{defaultFn:this._defRemoveFn,emitFacade:!0}})},next:function(){var e;while(this._q.length){e=this._q[0]=this._prepare(this._q[0]);if(!e||!e.until())break;this.fire(i,{callback:e}),e=null}return e||null},_defShiftFn:function(e){this.indexOf(e.callback)===0&&this._q.shift()},_prepare:function(t){if(a(t)&&t._prepared)return t;var r=e.merge(n.defaults,{context:this,args:[],_prepared:!0},this.defaults,a(t)?{fn:t}:t),i=e.bind(function(){i._running||i.iterations--,a(i.fn)&&i.fn.apply(i.context||e,e.Array(i.args))},this);return e.mix(i,r)},run:function(){var e,t=!0;if(this._executing)return this._running=!0,this;for(e=this.next();e&&!this.isRunning();e=this.next()){t=e.timeout<0?this._execute(e):this._schedule(e);if(!t)break}return e||this.fire("complete"),this},_execute:function(e){this._running=e._running=!0,this._executing=e,e.iterations--,this.fire(r,{callback:e});var t=this._running&&e.autoContinue;return this._running=e._running=!1,this._executing=!1,t},_schedule:function(t){return this._running=e.later(t.timeout,this,function(){this._execute(t)&&this.run()}),!1},isRunning:function(){return!!this._running},_defExecFn:function(e){e.callback()},add:function(){return this.fire("add",{callbacks:e.Array(arguments,0,!0)}),this},_defAddFn:function(t){var n=this._q,r=[];e.Array.each(t.callbacks,function(e){u(e)&&(n.push(e),r.push(e))}),t.added=r},pause:function(){return this._running&&u(this._running)&&this._running.cancel(),this._running=!1,this},stop:function(){return this._q=[],this._running&&u(this._running)&&(this._running.cancel(),this._running=!1),this._executing||this.run(),this},indexOf:function(e){var t=0,n=this._q.length,r;for(;t<n;++t){r=this._q[t];if(r===e||r.id===e)return t}return-1},getCallback:function(e){var t=this.indexOf(e);return t>-1?this._q[t]:null},promote:function(e){var t={callback:e},n;return this.isRunning()?n=this.after(i,function(){this.fire(s,t),n.detach()},this):this.fire(s,t),this},_defPromoteFn:function(e){var t=this.indexOf(e.callback),n=t>-1?this._q.splice(t,1)[0]:null;e.promoted=n,n&&this._q.unshift(n)},remove:function(e){var t={callback:e},n;return this.isRunning()?n=this.after(i,function(){this.fire(o,t),n.detach()},this):this.fire(o,t),this},_defRemoveFn:function(e){var t=this.indexOf(e.callback);e.removed=t>-1?this._q.splice(t,1)[0]:null},size:function(){return this.isRunning()||this.next(),this._q.length}})},"@VERSION@",{requires:["event-custom"]});