/*

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

Code licensed under the BSD License:

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

version: 3.0.0b1

build: 1163

*/

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

/**

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

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

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

 * even across configured timeouts.</p>

 *

 * @module queue

 * @submodule queue-run

 */

/**

 * <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>: -1 (synchronous operation)</li>

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

 * </ul>

 *

 * @property AsyncQueue.defaults

 * @type {Object}

 * @static

 */

Queue.defaults = Y.mix({

    autoContinue : true,

    iterations   : 1,

    timeout      : -1,

    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

     * @protected

     */

    _running : false,

    /**

     * Initializes the AsyncQueue instance properties and events.

     *

     * @method _init

     * @protected

     */

    _init : function () {

        Y.EventTarget.call(this, { 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 },

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

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

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

            'remove'  : { defaultFn : this._defRemoveFn }

        });

        */

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

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

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

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

        this.publish('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 "shift" 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;

        for (callback = this.next();

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

            callback = this.next())

        {

            cont = (callback.timeout < 0) ?

                this._execute(callback) :

                this._schedule(callback);

        }

        if (!callback) {

            /**

             * Event fired after the last queued callback is executed.

             * @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;

        callback.iterations--;

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

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

        this._running = callback._running = 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 "execute" 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 "add" 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 (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 = [];

        return this.pause();

    },

    /** 

     * 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);