queue-io.js revision 6ebbed8e0bf93478b8a9f7e3873c637039b93ea2
var _protoInit = Y.Queue.prototype._init;
/**
* Adds support for callback configuration key <code>pauseForIOResponse</code>.
* This will trigger the Queue to pause until all Y.io requests issued from
* inside the callback have received a response.
*
* @module queue
* @submodule queue-io
* @for Queue
*/
Y.mix(Y.Queue.prototype, {
_init : function () {
_protoInit.apply(this,arguments);
this.on('executeCallback',this._bindIOListeners);
this.after('executeCallback',this._detachIOStartListener);
return this;
},
/**
* Collection of outstanding io transaction ids that must complete before
* the Queue continues. Used during execution of callbacks configured with
* waitForIOResponse set to true.
*
* @property _waiting
* @type {Array}
* @protected
*/
_waiting : null,
/**
* Event listener for global io:start event to cache active io transactions.
*
* @property _ioStartSub
* @type {Object}
* @protected
*/
_ioStartSub : null,
/**
* Event listener for global io:success event to mark off io transactions,
* eventually restarting the Queue after all are complete or aborted.
*
* @property _ioSuccessSub
* @type {Object}
* @protected
*/
_ioSuccessSub : null,
/**
* Event listener for global io:success event to mark off io transactions,
* eventually restarting the Queue after all are complete or aborted.
*
* @property _ioFailureSub
* @type {Object}
* @protected
*/
_ioFailureSub : null,
/**
* Event listener for global io:abort event to mark off io transactions,
* eventually restarting the Queue after all are complete or aborted.
*
* @property _ioAbortSub
* @type {Object}
* @protected
*/
_ioAbortSub : null,
/**
* Event listener on the Queue to trigger detaching event subscriptions for
* a given callback when that callback is shifted off the queue.
*
* @property _shiftSub
* @type {Object}
* @protected
*/
_shiftSub : null,
isReady : function () {
return !this._tId && !this._waiting;
},
/**
* Attaches event listeners to IO and the Queue itself to monitor for new
* Y.io requests, to trigger the waiting process accordingly.
*
* @method _bindIOListeners
* @protected
*/
_bindIOListeners : function (callback) {
if (callback.waitForIOResponse) {
this._ioStartSub = Y.on('io:start',
Y.bind(this._ioStartHandler,this));
this._ioSuccessSub = Y.on('io:success',
Y.bind(this._ioEndHandler,this));
this._ioFailureSub = Y.on('io:failure',
Y.bind(this._ioEndHandler,this));
this._ioAbortSub = Y.on('io:abort',
Y.bind(this._ioEndHandler,this));
this._shiftSub = this.on('shiftCallback',
this._detachIOListeners);
}
},
/**
* Detaches event listener from io:start so new transactions spawned while
* the current callback is waiting are not considered required for
* continuing.
*
* @method _detachIOStartListener
* @protected
*/
_detachIOStartListener : function (callback) {
if (this._ioStartSub) {
this._ioStartSub.detach();
this._ioStartSub = null;
}
},
/**
* Stores the ids of initiated Y.io transactions for completion tracking.
*
* @method _ioStartHandler
* @param id {Number} the Y.io transaction id
* @protected
*/
_ioStartHandler : function (id) {
this._waiting = this._waiting || {};
this._waiting[id] = true;
},
/**
* Marks a Y.io transaction id as completed (or aborted). If all Y.io
* transactions generated by the callback have received responses, signal
* the Queue to continue.
*
* @method _ioEndHandler
* @param id {Number} the Y.io transaction id
* @protected
*/
_ioEndHandler : function (id) {
var resume = !this._waiting,
self = this;
if (!resume) {
delete this._waiting[id];
resume = !Y.Object.keys(this._waiting).length;
}
if (resume) {
this._waiting = null;
// FIXME: if next callback is synchronous, it will execute before
// the io success handler. Delaying with setTimeout fails the
// functional requirement that callbacks with negative timeouts
// execute in the same thread of execution as the prior callback.
// Async callbacks are in race condition with io event callback?
setTimeout(function () { self.run(); }, 0);
}
},
/**
* Detaches the event listeners to prevent processing noise during Queue
* execution.
*
* @method _detachIOListeners
* @protected
*/
_detachIOListeners : function () {
this._ioSuccessSub.detach();
this._ioFailureSub.detach();
this._ioAbortSub.detach();
this._shiftSub.detach();
this._ioSuccessSub = this._ioFailureSub =
this._ioAbortSub = this._shiftSub = null;
}
},true);
/**
* Add any number of callbacks to the end of the queue. Callbacks passed
* in as functions will be wrapped in a callback object.
*
* Callbacks can be function references or object literals with these keys:
* <dl>
* <dt>fn</dt>
* <dd>{Function} REQUIRED the callback function.</dd>
* <dt>name</dt>
* <dd>{String} a reference name to use for promotion or access</dd>
* <dt>context</dt>
* <dd>{Object} the context from which to call the callback function.</dd>
* <dt>timeout</dt>
* <dd>{number} millisecond delay to wait after previous callback
* completion before executing this callback. Negative
* values cause immediate blocking execution. Default 0.</dd>
* <dt>until</dt>
* <dd>{Function} boolean function executed before each iteration.
* Return true to indicate callback completion.</dd>
* <dt>iterations</dt>
* <dd>{Number} number of times to execute the callback before
* proceeding to the next callback in the queue.
* Incompatible with <code>until</code>.</dd>
* <dt>args</dt>
* <dd>{Array} array of arguments passed to callback function</dd>
* </dl>
*
* @method add
* @param callback* {Function|Object} Any number of callbacks
* @return {Queue} the Queue instance
*/