← Back to branch summary

~ubuntu-branches/ubuntu/utopic/moodle/utopic

« back to all changes in this revision

Viewing changes to lib/yuilib/3.9.1/build/async-queue/async-queue-debug.js

  • Committer: Package Import Robot
  • Author(s): Thijs Kinkhorst
  • Date: 2014-05-12 16:10:38 UTC
  • mfrom: (36.1.3 sid)
  • Revision ID: package-import@ubuntu.com-20140512161038-puyqf65k4e0s8ytz
Tags: 2.6.3-1
New upstream release.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/yuilib/3.9.1/build/async-queue/async-queue-debug.js
1
 
/* YUI 3.9.1 (build 5852) Copyright 2013 Yahoo! Inc. http://yuilibrary.com/license/ */
2
 
YUI.add('async-queue', function (Y, NAME) {
3
 
 
4
 
/**
5
 
 * <p>AsyncQueue allows you create a chain of function callbacks executed
6
 
 * via setTimeout (or synchronously) that are guaranteed to run in order.
7
 
 * Items in the queue can be promoted or removed.  Start or resume the
8
 
 * execution chain with run().  pause() to temporarily delay execution, or
9
 
 * stop() to halt and clear the queue.</p>
10
 
 *
11
 
 * @module async-queue
12
 
 */
13
 
 
14
 
/**
15
 
 * <p>A specialized queue class that supports scheduling callbacks to execute
16
 
 * sequentially, iteratively, even asynchronously.</p>
17
 
 *
18
 
 * <p>Callbacks can be function refs or objects with the following keys.  Only
19
 
 * the <code>fn</code> key is required.</p>
20
 
 *
21
 
 * <ul>
22
 
 * <li><code>fn</code> -- The callback function</li>
23
 
 * <li><code>context</code> -- The execution context for the callbackFn.</li>
24
 
 * <li><code>args</code> -- Arguments to pass to callbackFn.</li>
25
 
 * <li><code>timeout</code> -- Millisecond delay before executing callbackFn.
26
 
 *                     (Applies to each iterative execution of callback)</li>
27
 
 * <li><code>iterations</code> -- Number of times to repeat the callback.
28
 
 * <li><code>until</code> -- Repeat the callback until this function returns
29
 
 *                         true.  This setting trumps iterations.</li>
30
 
 * <li><code>autoContinue</code> -- Set to false to prevent the AsyncQueue from
31
 
 *                        executing the next callback in the Queue after
32
 
 *                        the callback completes.</li>
33
 
 * <li><code>id</code> -- Name that can be used to get, promote, get the
34
 
 *                        indexOf, or delete this callback.</li>
35
 
 * </ul>
36
 
 *
37
 
 * @class AsyncQueue
38
 
 * @extends EventTarget
39
 
 * @constructor
40
 
 * @param callback* {Function|Object} 0..n callbacks to seed the queue
41
 
 */
42
 
Y.AsyncQueue = function() {
43
 
    this._init();
44
 
    this.add.apply(this, arguments);
45
 
};
46
 
 
47
 
var Queue   = Y.AsyncQueue,
48
 
    EXECUTE = 'execute',
49
 
    SHIFT   = 'shift',
50
 
    PROMOTE = 'promote',
51
 
    REMOVE  = 'remove',
52
 
 
53
 
    isObject   = Y.Lang.isObject,
54
 
    isFunction = Y.Lang.isFunction;
55
 
 
56
 
/**
57
 
 * <p>Static default values used to populate callback configuration properties.
58
 
 * Preconfigured defaults include:</p>
59
 
 *
60
 
 * <ul>
61
 
 *  <li><code>autoContinue</code>: <code>true</code></li>
62
 
 *  <li><code>iterations</code>: 1</li>
63
 
 *  <li><code>timeout</code>: 10 (10ms between callbacks)</li>
64
 
 *  <li><code>until</code>: (function to run until iterations &lt;= 0)</li>
65
 
 * </ul>
66
 
 *
67
 
 * @property defaults
68
 
 * @type {Object}
69
 
 * @static
70
 
 */
71
 
Queue.defaults = Y.mix({
72
 
    autoContinue : true,
73
 
    iterations   : 1,
74
 
    timeout      : 10,
75
 
    until        : function () {
76
 
        this.iterations |= 0;
77
 
        return this.iterations <= 0;
78
 
    }
79
 
}, Y.config.queueDefaults || {});
80
 
 
81
 
Y.extend(Queue, Y.EventTarget, {
82
 
    /**
83
 
     * Used to indicate the queue is currently executing a callback.
84
 
     *
85
 
     * @property _running
86
 
     * @type {Boolean|Object} true for synchronous callback execution, the
87
 
     *                        return handle from Y.later for async callbacks.
88
 
     *                        Otherwise false.
89
 
     * @protected
90
 
     */
91
 
    _running : false,
92
 
 
93
 
    /**
94
 
     * Initializes the AsyncQueue instance properties and events.
95
 
     *
96
 
     * @method _init
97
 
     * @protected
98
 
     */
99
 
    _init : function () {
100
 
        Y.EventTarget.call(this, { prefix: 'queue', emitFacade: true });
101
 
 
102
 
        this._q = [];
103
 
 
104
 
        /** 
105
 
         * Callback defaults for this instance.  Static defaults that are not
106
 
         * overridden are also included.
107
 
         *
108
 
         * @property defaults
109
 
         * @type {Object}
110
 
         */
111
 
        this.defaults = {};
112
 
 
113
 
        this._initEvents();
114
 
    },
115
 
 
116
 
    /**
117
 
     * Initializes the instance events.
118
 
     *
119
 
     * @method _initEvents
120
 
     * @protected
121
 
     */
122
 
    _initEvents : function () {
123
 
        this.publish({
124
 
            'execute' : { defaultFn : this._defExecFn,    emitFacade: true },
125
 
            'shift'   : { defaultFn : this._defShiftFn,   emitFacade: true },
126
 
            'add'     : { defaultFn : this._defAddFn,     emitFacade: true },
127
 
            'promote' : { defaultFn : this._defPromoteFn, emitFacade: true },
128
 
            'remove'  : { defaultFn : this._defRemoveFn,  emitFacade: true }
129
 
        });
130
 
    },
131
 
 
132
 
    /**
133
 
     * Returns the next callback needing execution.  If a callback is
134
 
     * configured to repeat via iterations or until, it will be returned until
135
 
     * the completion criteria is met.
136
 
     *
137
 
     * When the queue is empty, null is returned.
138
 
     *
139
 
     * @method next
140
 
     * @return {Function} the callback to execute
141
 
     */
142
 
    next : function () {
143
 
        var callback;
144
 
 
145
 
        while (this._q.length) {
146
 
            callback = this._q[0] = this._prepare(this._q[0]);
147
 
            if (callback && callback.until()) {
148
 
                this.fire(SHIFT, { callback: callback });
149
 
                callback = null;
150
 
            } else {
151
 
                break;
152
 
            }
153
 
        }
154
 
 
155
 
        return callback || null;
156
 
    },
157
 
 
158
 
    /**
159
 
     * Default functionality for the &quot;shift&quot; event.  Shifts the
160
 
     * callback stored in the event object's <em>callback</em> property from
161
 
     * the queue if it is the first item.
162
 
     *
163
 
     * @method _defShiftFn
164
 
     * @param e {Event} The event object
165
 
     * @protected
166
 
     */
167
 
    _defShiftFn : function (e) {
168
 
        if (this.indexOf(e.callback) === 0) {
169
 
            this._q.shift();
170
 
        }
171
 
    },
172
 
 
173
 
    /**
174
 
     * Creates a wrapper function to execute the callback using the aggregated 
175
 
     * configuration generated by combining the static AsyncQueue.defaults, the
176
 
     * instance defaults, and the specified callback settings.
177
 
     *
178
 
     * The wrapper function is decorated with the callback configuration as
179
 
     * properties for runtime modification.
180
 
     *
181
 
     * @method _prepare
182
 
     * @param callback {Object|Function} the raw callback
183
 
     * @return {Function} a decorated function wrapper to execute the callback
184
 
     * @protected
185
 
     */
186
 
    _prepare: function (callback) {
187
 
        if (isFunction(callback) && callback._prepared) {
188
 
            return callback;
189
 
        }
190
 
 
191
 
        var config = Y.merge(
192
 
            Queue.defaults,
193
 
            { context : this, args: [], _prepared: true },
194
 
            this.defaults,
195
 
            (isFunction(callback) ? { fn: callback } : callback)),
196
 
            
197
 
            wrapper = Y.bind(function () {
198
 
                if (!wrapper._running) {
199
 
                    wrapper.iterations--;
200
 
                }
201
 
                if (isFunction(wrapper.fn)) {
202
 
                    wrapper.fn.apply(wrapper.context || Y,
203
 
                                     Y.Array(wrapper.args));
204
 
                }
205
 
            }, this);
206
 
            
207
 
        return Y.mix(wrapper, config);
208
 
    },
209
 
 
210
 
    /**
211
 
     * Sets the queue in motion.  All queued callbacks will be executed in
212
 
     * order unless pause() or stop() is called or if one of the callbacks is
213
 
     * configured with autoContinue: false.
214
 
     *
215
 
     * @method run
216
 
     * @return {AsyncQueue} the AsyncQueue instance
217
 
     * @chainable
218
 
     */
219
 
    run : function () {
220
 
        var callback,
221
 
            cont = true;
222
 
 
223
 
        for (callback = this.next();
224
 
            cont && callback && !this.isRunning();
225
 
            callback = this.next())
226
 
        {
227
 
            cont = (callback.timeout < 0) ?
228
 
                this._execute(callback) :
229
 
                this._schedule(callback);
230
 
        }
231
 
 
232
 
        if (!callback) {
233
 
            /**
234
 
             * Event fired after the last queued callback is executed.
235
 
             * @event complete
236
 
             */
237
 
            this.fire('complete');
238
 
        }
239
 
 
240
 
        return this;
241
 
    },
242
 
 
243
 
    /**
244
 
     * Handles the execution of callbacks. Returns a boolean indicating
245
 
     * whether it is appropriate to continue running.
246
 
     *
247
 
     * @method _execute
248
 
     * @param callback {Object} the callback object to execute
249
 
     * @return {Boolean} whether the run loop should continue
250
 
     * @protected
251
 
     */
252
 
    _execute : function (callback) {
253
 
        this._running = callback._running = true;
254
 
 
255
 
        callback.iterations--;
256
 
        this.fire(EXECUTE, { callback: callback });
257
 
 
258
 
        var cont = this._running && callback.autoContinue;
259
 
 
260
 
        this._running = callback._running = false;
261
 
 
262
 
        return cont;
263
 
    },
264
 
 
265
 
    /**
266
 
     * Schedules the execution of asynchronous callbacks.
267
 
     *
268
 
     * @method _schedule
269
 
     * @param callback {Object} the callback object to execute
270
 
     * @return {Boolean} whether the run loop should continue
271
 
     * @protected
272
 
     */
273
 
    _schedule : function (callback) {
274
 
        this._running = Y.later(callback.timeout, this, function () {
275
 
            if (this._execute(callback)) {
276
 
                this.run();
277
 
            }
278
 
        });
279
 
 
280
 
        return false;
281
 
    },
282
 
 
283
 
    /**
284
 
     * Determines if the queue is waiting for a callback to complete execution.
285
 
     *
286
 
     * @method isRunning
287
 
     * @return {Boolean} true if queue is waiting for a 
288
 
     *                   from any initiated transactions
289
 
     */
290
 
    isRunning : function () {
291
 
        return !!this._running;
292
 
    },
293
 
 
294
 
    /**
295
 
     * Default functionality for the &quot;execute&quot; event.  Executes the
296
 
     * callback function
297
 
     *
298
 
     * @method _defExecFn
299
 
     * @param e {Event} the event object
300
 
     * @protected
301
 
     */
302
 
    _defExecFn : function (e) {
303
 
        e.callback();
304
 
    },
305
 
 
306
 
    /**
307
 
     * Add any number of callbacks to the end of the queue. Callbacks may be
308
 
     * provided as functions or objects.
309
 
     *
310
 
     * @method add
311
 
     * @param callback* {Function|Object} 0..n callbacks
312
 
     * @return {AsyncQueue} the AsyncQueue instance
313
 
     * @chainable
314
 
     */
315
 
    add : function () {
316
 
        this.fire('add', { callbacks: Y.Array(arguments,0,true) });
317
 
 
318
 
        return this;
319
 
    },
320
 
 
321
 
    /**
322
 
     * Default functionality for the &quot;add&quot; event.  Adds the callbacks
323
 
     * in the event facade to the queue. Callbacks successfully added to the
324
 
     * queue are present in the event's <code>added</code> property in the
325
 
     * after phase.
326
 
     *
327
 
     * @method _defAddFn
328
 
     * @param e {Event} the event object
329
 
     * @protected
330
 
     */
331
 
    _defAddFn : function(e) {
332
 
        var _q = this._q,
333
 
            added = [];
334
 
 
335
 
        Y.Array.each(e.callbacks, function (c) {
336
 
            if (isObject(c)) {
337
 
                _q.push(c);
338
 
                added.push(c);
339
 
            }
340
 
        });
341
 
 
342
 
        e.added = added;
343
 
    },
344
 
 
345
 
    /**
346
 
     * Pause the execution of the queue after the execution of the current
347
 
     * callback completes.  If called from code outside of a queued callback,
348
 
     * clears the timeout for the pending callback. Paused queue can be
349
 
     * restarted with q.run()
350
 
     *
351
 
     * @method pause
352
 
     * @return {AsyncQueue} the AsyncQueue instance
353
 
     * @chainable
354
 
     */
355
 
    pause: function () {
356
 
        if (isObject(this._running)) {
357
 
            this._running.cancel();
358
 
        }
359
 
 
360
 
        this._running = false;
361
 
 
362
 
        return this;
363
 
    },
364
 
 
365
 
    /**
366
 
     * Stop and clear the queue after the current execution of the
367
 
     * current callback completes.
368
 
     *
369
 
     * @method stop
370
 
     * @return {AsyncQueue} the AsyncQueue instance
371
 
     * @chainable
372
 
     */
373
 
    stop : function () { 
374
 
        this._q = [];
375
 
 
376
 
        return this.pause();
377
 
    },
378
 
 
379
 
    /** 
380
 
     * Returns the current index of a callback.  Pass in either the id or
381
 
     * callback function from getCallback.
382
 
     *
383
 
     * @method indexOf
384
 
     * @param callback {String|Function} the callback or its specified id
385
 
     * @return {Number} index of the callback or -1 if not found
386
 
     */
387
 
    indexOf : function (callback) {
388
 
        var i = 0, len = this._q.length, c;
389
 
 
390
 
        for (; i < len; ++i) {
391
 
            c = this._q[i];
392
 
            if (c === callback || c.id === callback) {
393
 
                return i;
394
 
            }
395
 
        }
396
 
 
397
 
        return -1;
398
 
    },
399
 
 
400
 
    /**
401
 
     * Retrieve a callback by its id.  Useful to modify the configuration
402
 
     * while the queue is running.
403
 
     *
404
 
     * @method getCallback
405
 
     * @param id {String} the id assigned to the callback
406
 
     * @return {Object} the callback object
407
 
     */
408
 
    getCallback : function (id) {
409
 
        var i = this.indexOf(id);
410
 
 
411
 
        return (i > -1) ? this._q[i] : null;
412
 
    },
413
 
 
414
 
    /**
415
 
     * Promotes the named callback to the top of the queue. If a callback is
416
 
     * currently executing or looping (via until or iterations), the promotion
417
 
     * is scheduled to occur after the current callback has completed.
418
 
     *
419
 
     * @method promote
420
 
     * @param callback {String|Object} the callback object or a callback's id
421
 
     * @return {AsyncQueue} the AsyncQueue instance
422
 
     * @chainable
423
 
     */
424
 
    promote : function (callback) {
425
 
        var payload = { callback : callback },e;
426
 
 
427
 
        if (this.isRunning()) {
428
 
            e = this.after(SHIFT, function () {
429
 
                    this.fire(PROMOTE, payload);
430
 
                    e.detach();
431
 
                }, this);
432
 
        } else {
433
 
            this.fire(PROMOTE, payload);
434
 
        }
435
 
 
436
 
        return this;
437
 
    },
438
 
 
439
 
    /**
440
 
     * <p>Default functionality for the &quot;promote&quot; event.  Promotes the
441
 
     * named callback to the head of the queue.</p>
442
 
     *
443
 
     * <p>The event object will contain a property &quot;callback&quot;, which
444
 
     * holds the id of a callback or the callback object itself.</p>
445
 
     *
446
 
     * @method _defPromoteFn
447
 
     * @param e {Event} the custom event
448
 
     * @protected
449
 
     */
450
 
    _defPromoteFn : function (e) {
451
 
        var i = this.indexOf(e.callback),
452
 
            promoted = (i > -1) ? this._q.splice(i,1)[0] : null;
453
 
 
454
 
        e.promoted = promoted;
455
 
 
456
 
        if (promoted) {
457
 
            this._q.unshift(promoted);
458
 
        }
459
 
    },
460
 
 
461
 
    /**
462
 
     * Removes the callback from the queue.  If the queue is active, the
463
 
     * removal is scheduled to occur after the current callback has completed.
464
 
     *
465
 
     * @method remove
466
 
     * @param callback {String|Object} the callback object or a callback's id
467
 
     * @return {AsyncQueue} the AsyncQueue instance
468
 
     * @chainable
469
 
     */
470
 
    remove : function (callback) {
471
 
        var payload = { callback : callback },e;
472
 
 
473
 
        // Can't return the removed callback because of the deferral until
474
 
        // current callback is complete
475
 
        if (this.isRunning()) {
476
 
            e = this.after(SHIFT, function () {
477
 
                    this.fire(REMOVE, payload);
478
 
                    e.detach();
479
 
                },this);
480
 
        } else {
481
 
            this.fire(REMOVE, payload);
482
 
        }
483
 
 
484
 
        return this;
485
 
    },
486
 
 
487
 
    /**
488
 
     * <p>Default functionality for the &quot;remove&quot; event.  Removes the
489
 
     * callback from the queue.</p>
490
 
     *
491
 
     * <p>The event object will contain a property &quot;callback&quot;, which
492
 
     * holds the id of a callback or the callback object itself.</p>
493
 
     *
494
 
     * @method _defRemoveFn
495
 
     * @param e {Event} the custom event
496
 
     * @protected
497
 
     */
498
 
    _defRemoveFn : function (e) {
499
 
        var i = this.indexOf(e.callback);
500
 
 
501
 
        e.removed = (i > -1) ? this._q.splice(i,1)[0] : null;
502
 
    },
503
 
 
504
 
    /**
505
 
     * Returns the number of callbacks in the queue.
506
 
     *
507
 
     * @method size
508
 
     * @return {Number}
509
 
     */
510
 
    size : function () {
511
 
        // next() flushes callbacks that have met their until() criteria and
512
 
        // therefore shouldn't count since they wouldn't execute anyway.
513
 
        if (!this.isRunning()) {
514
 
            this.next();
515
 
        }
516
 
 
517
 
        return this._q.length;
518
 
    }
519
 
});
520
 
 
521
 
 
522
 
 
523
 
}, '3.9.1', {"requires": ["event-custom"]});