/loggerhead/trunk

/*
Copyright (c) 2008, Yahoo! Inc. All rights reserved.
Code licensed under the BSD License:
http://developer.yahoo.net/yui/license.txt
version: 3.0.0pr1
*/
YUI.add('queue', function(Y) {

/**
 * Mechanism to execute a series of callbacks in a non-blocking queue.  Each
 * callback is executed via setTimout unless configured with a negative
 * timeout, in which case it is run in blocking mode in the same execution
 * thread as the previous callback.  Callbacks can be function references or
 * object literals with the following keys:
 * <ul>
 *    <li><code>fn</code> - {Function} REQUIRED the callback function.</li>
 *    <li><code>timeout</code> - {number} millisecond delay to wait after previous callback completion before executing this callback.  Negative values cause immediate blocking execution.  Default 0.</li>
 *    <li><code>until</code> - {Function} boolean function executed before each iteration.  Return true to indicate callback completion.</li>
 *    <li><code>iterations</code> - {Number} number of times to execute the callback before proceeding to the next callback in the queue. Incompatible with <code>until</code>.</li>
 * </ul>
 *
 * @module queue
 * @class Queue
 * @constructor
 * @param callback* {Function|Object} Any number of callbacks to initialize the queue
 */
Y.Queue = function () {
    // Factory or Constructor
    var me = this instanceof Y.Queue ? this : new Y.Queue();

    /**
     * The callback queue
     * @property q
     * @type {Array}
     * @protected
     */
    me.q = [];

    return me.add.apply(me,arguments);
};

Y.Queue.prototype = {
    /**
     * Timeout id used to pause or stop execution and indicate the execution
     * state of the Queue.  0 indicates paused or stopped, negatives indicate
     * blocking execution, and positives indicate non-blocking execution.
     * @property id
     * @type {number}
     * @protected
     */
    id   : 0,

    /**
     * Execute the queue callbacks (also resumes paused Queue).
     * @method run
     * @return {Queue} the Queue instance
     */
    run : function () {
        // Grab the first callback in the queue
        var c  = this.q[0],
            fn;

        // If there is no callback in the queue or the Queue is currently
        // in an execution mode, return
        if (!c) {
            /**
             * Event fired after the last queued callback is executed.  Not
             * fired if the Queue is stopped via q.stop().
             * @event end
             */
            this.fire('end');
            return this;
        } else if (this.id) {
            return this;
        }

        fn = c.fn || c;

        if (typeof fn === 'function') {
            var ms   = c.timeout || 0,
                me   = this;

            // Execute immediately if the callback timeout is negative.
            if (ms < 0) {
                this.id = ms;
                if (c.until) { // test .until condition
                    for (;!c.until();) {
                        this._exec(fn,c);
                    }
                } else if (c.iterations) { // test .iterations
                    for (;c.iterations-- > 0;) {
                        this._exec(fn,c);
                    }
                } else { // single shot callback
                    this._exec(fn,c);
                }
                this._shift();
                this.id = 0;
                return this.run();
            } else {
                if (c.until) { // test .until condition
                    if (c.until()) {
                        // Move to the next callback
                        this._shift();
                        return this.run();
                    }
                } else if (!c.iterations || !--c.iterations) { // .iterations
                    this._shift();
                }

                // Set to execute after the configured timeout
                this.id = setTimeout(function () {
                    me._exec(fn,c);

                    // Loop unless the Queue was paused from inside the callback
                    if (me.id) {
                        // Indicate ready to run state
                        me.id = 0;
                        // Start the fun all over again
                        me.run();
                    }
                },ms);
            }
        }

        return this;
    },

    /**
     * Executes the callback function
     * @method _exec
     * @param fn {Function} the function to execute
     * @param c {Object|Function} the callback as defined during add(c)
     * @protected
     */
    _exec : function (fn,c) {
        /**
         * Fired before a callback is executed
         * @event beforeCallback
         * @param o {Object} Object literal with the following keys:
         * <dl>
         * <dt>fn</dt><dd>The function about to be executed</dd>
         * <dt>callback</dt><dd>The callback as provided to <code>add(..)</code></dd>
         * </dl>
         */
        this.fire('beforeCallback',{fn:fn,callback:c});

        fn.call(this);

        /**
         * Fired before a callback is executed
         * @event afterCallback
         * @param o {Object} Object literal with the following keys:
         * <dl>
         * <dt>fn</dt><dd>The function just executed</dd>
         * <dt>callback</dt><dd>The callback as provided to <code>add(..)</code></dd>
         * </dl>
         */
        this.fire('afterCallback',{fn:fn,callback:c});
    },

    /**
     * Shifts the first callback off the Queue
     * @method _shift
     * @private
     */
    _shift : function () {
        /**
         * Fired after a callback is shifted from the Queue
         * @event shiftCallback
         * @param callback {Function|Object} The callback passed to <code>add(..)</code>
         */
        this.fire('shiftCallback',this.q.shift());
    },
    
    /**
     * Add any number of callbacks to the end of the queue
     * @method add
     * @param callback* {Function|Object} Any number of callbacks
     * @return {Queue} the Queue instance
     */
    add  : function () {
        var callbacks = Y.Array(arguments,0,true);
        this.q.splice.apply(this.q,[this.q.length,0].concat(callbacks));

        /**
         * Fired from within <code>add(..)</code> after callbacks are queued
         * @event addCallback
         * @param callbacks {Array} Array of callbacks passed to <code>add(..)</code>
         */
        this.fire('addCallback',callbacks);
        return this;
    },

    /**
     * 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 {Queue} the Queue instance
     */
    pause: function () {
        clearTimeout(this.id);
        this.id = 0;

        /**
         * Fired after Queue is paused
         * @event pause
         */
        this.fire('pause');
        return this;
    },

    /**
     * Stop and clear the Queue's queue after the current execution of the
     * current callback completes.
     * @method stop
     * @return {Queue} the Queue instance
     */
    stop : function () { 
        this.pause();
        this.q = [];

        /**
         * Fired after Queue is stopped
         * @event stop
         */
        this.fire('stop');
        return this;
    }
};
Y.augment(Y.Queue,Y.Event.Target);


}, '3.0.0pr1' );