← Back to branch summary

~ubuntu-branches/ubuntu/precise/whoopsie-daisy/precise-proposed

« back to all changes in this revision

Viewing changes to backend/stats/static/js/yui/docs/async-queue/index.html

  • Committer: Package Import Robot
  • Author(s): Evan Dandrea
  • Date: 2012-04-18 13:04:36 UTC
  • Revision ID: package-import@ubuntu.com-20120418130436-vmt93p8fds516lws
Tags: 0.1.32
Fix failing tests on powerpc and ARM.

Show diffs side-by-side

added added

removed removed

Lines of Context:
backend/stats/static/js/yui/docs/async-queue/index.html
 
1
<!DOCTYPE html>
 
2
<html lang="en">
 
3
<head>
 
4
    <meta charset="utf-8">
 
5
    <title>AsyncQueue</title>
 
6
    <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Maven+Pro:400,700">
 
7
    <link rel="stylesheet" href="../../build/cssgrids/grids-min.css">
 
8
    <link rel="stylesheet" href="../assets/css/main.css">
 
9
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
 
10
    <script src="../../build/yui/yui-min.js"></script>
 
11
</head>
 
12
<body>
 
13
 
 
14
<div id="doc">
 
15
    <h1>AsyncQueue</h1>
 
16
 
 
17
    
 
18
        <a href="#toc" class="jump">Jump to Table of Contents</a>
 
19
    
 
20
 
 
21
    <div class="yui3-g">
 
22
        <div class="yui3-u-3-4">
 
23
            <div id="main">
 
24
                <div class="content"><div class="intro" class="component">
 
25
    <p>
 
26
        AsyncQueue allows you create a chain of function callbacks executed via
 
27
        <code>setTimeout</code> that are guaranteed to run in order.  This can
 
28
        enable progressive incremental rendering of your UI so your users can
 
29
        begin to see and interact with your page while the infrastructure is
 
30
        being built.  Similarly, process-intensive operations that will lock up
 
31
        the UI while the JavaScript is being executed can be broken up into
 
32
        chunks, helping to keep your interface responsive.
 
33
    </p>
 
34
</div>
 
35
 
 
36
<h2 id="getting-started">Getting Started</h2>
 
37
 
 
38
<p>
 
39
To include the source files for AsyncQueue and its dependencies, first load
 
40
the YUI seed file if you haven't already loaded it.
 
41
</p>
 
42
 
 
43
<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.5.0&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>
 
44
 
 
45
 
 
46
<p>
 
47
Next, create a new YUI instance for your application and populate it with the
 
48
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
 
49
YUI will automatically load any dependencies required by the modules you
 
50
specify.
 
51
</p>
 
52
 
 
53
<pre class="code prettyprint">&lt;script&gt;
 
54
&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
 
55
YUI().use(&#x27;async-queue&#x27;, function (Y) {
 
56
    &#x2F;&#x2F; AsyncQueue is available and ready for use. Add implementation
 
57
    &#x2F;&#x2F; code here.
 
58
});
 
59
&lt;&#x2F;script&gt;</pre>
 
60
 
 
61
 
 
62
<p>
 
63
For more information on creating YUI instances and on the
 
64
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
 
65
documentation for the <a href="../yui/index.html">YUI Global Object</a>.
 
66
</p>
 
67
 
 
68
 
 
69
<h2 id="using">Using AsyncQueue</h2>
 
70
 
 
71
<h3 id="interacting">Creating and interacting with an AsyncQueue</h3>
 
72
 
 
73
<p>
 
74
    AsyncQueues manage an array of callbacks that can be either simple function
 
75
    references or <a href="#callbacks">objects with specific keys</a>.  The
 
76
    primary methods on AsyncQueue are <code>add</code> and
 
77
    <code>run</code>.
 
78
</p>
 
79
 
 
80
<p>
 
81
    When <code>run()</code> is invoked, each callback is executed in turn,
 
82
    either synchronously or via <code>setTimeout</code> (depending on the
 
83
    configuration of the callback or of the AsyncQueue instance).
 
84
</p>
 
85
 
 
86
<p>
 
87
    Queued callbacks can also be promoted to the top of the queue or removed
 
88
    from it.
 
89
</p>
 
90
 
 
91
<pre class="code prettyprint">var q = new Y.AsyncQueue(callbackB, someTask, callbackA, callbackC);
 
92
q.add(callbackD, callbackE); &#x2F;&#x2F; B, someTask, A, C, D, E
 
93
q.promote(callbackA);        &#x2F;&#x2F; A, B, someTask, C, D, E
 
94
q.remove(someTask);          &#x2F;&#x2F; A, B, C, D, E
 
95
q.run();                     &#x2F;&#x2F; execute A, then B, then C, then D, then E</pre>
 
96
 
 
97
 
 
98
 
 
99
<h4 id="stopping">Pausing and stopping an AsyncQueue</h4>
 
100
 
 
101
<p>
 
102
    In addition to <code>run()</code>, AsyncQueue instances also have
 
103
    <code>pause()</code> and <code>stop()</code> methods to interrupt the run
 
104
    state.
 
105
</p>
 
106
 
 
107
<p>
 
108
    To wait for an external process to complete, such as an XHR request, call
 
109
    <code>pause()</code>, then <code>run()</code> again to resume
 
110
    execution.
 
111
</p>
 
112
                
 
113
<p>
 
114
    Call <code>stop()</code> to terminate execution and flush the AsyncQueue.
 
115
</p>
 
116
 
 
117
<pre class="code prettyprint">&#x2F;&#x2F; Seed the instance with callbacks
 
118
var q = new Y.AsyncQueue(
 
119
    MyApp.doSomething,
 
120
 
 
121
    &#x2F;&#x2F; The second callback will pause the Queue and send an XHR for data
 
122
    function () {
 
123
        q.pause();
 
124
 
 
125
        &#x2F;&#x2F; Send the asynchronous XHR
 
126
        Y.io(MyApp.getDataUri(), { on: {
 
127
            success : function (xid,o) {
 
128
                try {
 
129
                    var data = Y.JSON.parse(o.responseText);
 
130
                }
 
131
                catch (e) {
 
132
                    MyApp.showErrorStatus();
 
133
                    q.stop();
 
134
                }
 
135
 
 
136
                MyApp.processData(data);
 
137
 
 
138
                &#x2F;&#x2F; In the XHR callback, restart the AsyncQueue if successful
 
139
                q.run();
 
140
            },
 
141
            failure : function () {
 
142
                MyApp.showErrorStatus();
 
143
                &#x2F;&#x2F; Stop the AsyncQueue if anything goes wrong
 
144
                q.stop();
 
145
            }
 
146
        }});
 
147
    },
 
148
 
 
149
    &#x2F;&#x2F; The third callback will do partial updates until complete
 
150
    {
 
151
        fn:    Y.bind(MyApp.updateUI,MyApp),
 
152
        until: function () {
 
153
            return MyApp.remainingData &gt;= 0;
 
154
        }
 
155
    },
 
156
    MyApp.doSomethingElse);
 
157
 
 
158
q.run();</pre>
 
159
 
 
160
 
 
161
 
 
162
<h4 id="callbacks">About AsyncQueue callbacks</h4>
 
163
 
 
164
<p>
 
165
    AsyncQueue callbacks can be simple function references or object literals
 
166
    with the following keys:
 
167
</p>
 
168
 
 
169
<table>
 
170
<thead>
 
171
    <tr>
 
172
        <th>property</th>
 
173
        <th>description</th>
 
174
        <th>default</th>
 
175
    </tr>
 
176
</thead>
 
177
<tbody>
 
178
    <tr>
 
179
        <td><code>fn</code></td>
 
180
        <td><strong>Required</strong>.  The callback function to execute.</td>
 
181
        <td>(none)</td>
 
182
    </tr>
 
183
    <tr>
 
184
        <td><code>context</code></td>
 
185
        <td>The context from which to execute the callback function.</td>
 
186
        <td>The AsyncQueue instance</td>
 
187
    </tr>
 
188
    <tr>
 
189
        <td><code>args</code></td>
 
190
        <td>Array of arguments that will be passed as individual args to the callback function.</td>
 
191
        <td>(none)</td>
 
192
    </tr>
 
193
    <tr>
 
194
        <td><code>timeout</code></td>
 
195
        <td>Millisecond delay before each execution of this callback.  Set to -1 to trigger synchronous execution.</td>
 
196
        <td>10</td>
 
197
    </tr>
 
198
    <tr>
 
199
        <td><code>iterations</code></td>
 
200
        <td>The number of times to execute this callback before shifting it from the queue.</td>
 
201
        <td>1</td>
 
202
    </tr>
 
203
    <tr>
 
204
        <td><code>until</code></td>
 
205
        <td>A function that will return <code>true</code> when the current callback can be shifted from the queue.</td>
 
206
        <td>a function that tests against <code>iterations</code></td>
 
207
    </tr>
 
208
    <tr>
 
209
        <td><code>id</code></td>
 
210
        <td>Name given to this callback for ease of reference.</td>
 
211
        <td>(none)</td>
 
212
    </tr>
 
213
    <tr>
 
214
        <td><code>autoContinue</code></td>
 
215
        <td>Set to <code>false</code> to automatically <code>pause()</code> after this callback.</td>
 
216
        <td>true</td>
 
217
    </tr>
 
218
</tbody>
 
219
</table>
 
220
 
 
221
<h4 id="defaults">Class- and instance-level callback defaults</h4>
 
222
 
 
223
<p>
 
224
    AsyncQueue provides three places to configure callbacks (in decreasing
 
225
    precedence order):
 
226
</p>
 
227
 
 
228
<ol>
 
229
    <li>The callback object</li>
 
230
    <li>The AsyncQueue instance's <code>defaults</code> collection</li>
 
231
    <li>The class static <code>defaults</code> collection</li>
 
232
</ol>
 
233
 
 
234
<pre class="code prettyprint">&#x2F;&#x2F; All AsyncQueue instances will execute all callbacks synchronously by default
 
235
Y.AsyncQueue.defaults.timeout = -1;
 
236
 
 
237
var q = new Y.AsyncQueue();
 
238
 
 
239
&#x2F;&#x2F; run every callback in this instance twice before moving to the next callback
 
240
q.defaults.iterations = 2;
 
241
 
 
242
q.add(functionA,
 
243
      {
 
244
        fn: functionB,
 
245
        timeout: 100 &#x2F;&#x2F; this callback will be executed asynchronously
 
246
      });
 
247
 
 
248
&#x2F;&#x2F; functionA executes twice immediately, then after 100 milliseconds functionB
 
249
&#x2F;&#x2F; is executed, then after another 100ms functionB is executed again.
 
250
q.run();</pre>
 
251
 
 
252
 
 
253
 
 
254
<h4 id="sync">Synchronous mode for callback execution</h4>
 
255
<p>
 
256
    One of the main goals of the AsyncQueue is to provide a mechanism to
 
257
    prevent process-intensive operations from locking up the UI.  By default,
 
258
    AsyncQueue callbacks are executed via <code>setTimeout</code> to facilitate
 
259
    this.  The <code>timeout</code> configuration accepts -1 as a value to
 
260
    trigger synchronous callback execution.  Use this setting with caution.
 
261
</p>
 
262
                
 
263
<h4 id="chaining">About timeout chaining</h4>
 
264
 
 
265
<p>
 
266
    Timeout chaining is a strategy to address the lack of <a
 
267
    href="http://en.wikipedia.org/wiki/Thread_(computer_science)">multithreading</a>
 
268
    in JavaScript.  When complex or iterative code executes it can cause the
 
269
    page to stop responding until the running JavaScript process completes; it
 
270
    can also cause "non-responsive script" or "long-running script" dialogs to
 
271
    be presented to the user.  Both outcomes are detrimental to user
 
272
    experience.
 
273
</p>
 
274
 
 
275
<p>
 
276
    To address this, the operation can be split into chunks, and
 
277
    <code>setTimeout</code> can be used to yield control back to other
 
278
    operations between each chunk.  A common use case for this technique is to
 
279
    allow browser reflows to display DOM modifications incrementally while
 
280
    batches of work are being done in JavaScript.  For iterative functions, the
 
281
    code can execute a portion of the overall work, then schedule itself to run
 
282
    via <code>setTimeout</code>.
 
283
</p>
 
284
 
 
285
<p>The basic form of an iterative timeout chain is:</p>
 
286
 
 
287
<pre class="code prettyprint">(function () {
 
288
 
 
289
    &#x2F;* do a chunk of the work *&#x2F;
 
290
 
 
291
    if (&#x2F;* process completion check fails *&#x2F;) {
 
292
        &#x2F;&#x2F; Schedule myself for re-execution, picking up where I left off
 
293
        setTimeout(arguments.callee,0);
 
294
    }
 
295
})();</pre>
 
296
 
 
297
 
 
298
 
 
299
<p>
 
300
    When dealing with <code>setTimeout</code>, it's easy to introduce race
 
301
    conditions.  Because all timeouts are scheduled against the same timer and
 
302
    only one can run at a time, when two timeouts are separately scheduled, it
 
303
    is possible for them to execute out of intended order.
 
304
</p>
 
305
 
 
306
<p>
 
307
    AsyncQueue supports both "chunked operations" (by specifying callback
 
308
    timeouts) and "iterative operations" (by specifying callback
 
309
    <code>iterations</code> or <code>until</code> functions).  Furthermore,
 
310
    AsyncQueue manages the callback sequence and can therefore guarantee the
 
311
    execution order, so you avoid race conditions.
 
312
</p>
 
313
 
 
314
<h4 id="events">Exposed events</h4>
 
315
<p>
 
316
    AsyncQueue is based on EventTarget and instances emit the following events
 
317
    throughout their lifecycle:
 
318
</p>
 
319
 
 
320
<table>
 
321
<thead>
 
322
    <tr>
 
323
        <th>Event</th>
 
324
        <th>When</th>
 
325
        <th>Event payload</th>
 
326
    </tr>
 
327
</thead>
 
328
<tbody>
 
329
    <tr>
 
330
        <td><code>add</code></td>
 
331
        <td>Callbacks are added to the AsyncQueue.</td>
 
332
        <td><code>{ callbacks: (Array of callbacks added) }</code></td>
 
333
    </tr>
 
334
    <tr>
 
335
        <td><code>promote</code></td>
 
336
        <td>A callback is promoted.</td>
 
337
        <td><code>{ callback : (callback) }</code></td>
 
338
    </tr>
 
339
    <tr>
 
340
        <td><code>remove</code></td>
 
341
        <td>A callback is removed.</td>
 
342
        <td><code>{ callback : (callback) }</code></td>
 
343
    </tr>
 
344
    <tr>
 
345
        <td><code>execute</code></td>
 
346
        <td>A callback is executed.</td>
 
347
        <td><code>{ callback : (callback) }</code></td>
 
348
    </tr>
 
349
    <tr>
 
350
        <td><code>shift</code></td>
 
351
        <td>A callback is shifted from the AsyncQueue.</td>
 
352
        <td><code>{ callback : (callback) }</code></td>
 
353
    </tr>
 
354
    <tr>
 
355
        <td><code>complete</code></td>
 
356
        <td>After the last callback is finished executing.  <em>NOT</em> fired after <code>stop()</code>.</td>
 
357
        <td>(none)</td>
 
358
    </tr>
 
359
</tbody>
 
360
</table>
 
361
</div>
 
362
            </div>
 
363
        </div>
 
364
 
 
365
        <div class="yui3-u-1-4">
 
366
            <div class="sidebar">
 
367
                
 
368
                    <div id="toc" class="sidebox">
 
369
                        <div class="hd">
 
370
                            <h2 class="no-toc">Table of Contents</h2>
 
371
                        </div>
 
372
 
 
373
                        <div class="bd">
 
374
                            <ul class="toc">
 
375
<li>
 
376
<a href="#getting-started">Getting Started</a>
 
377
</li>
 
378
<li>
 
379
<a href="#using">Using AsyncQueue</a>
 
380
<ul class="toc">
 
381
<li>
 
382
<a href="#interacting">Creating and interacting with an AsyncQueue</a>
 
383
<ul class="toc">
 
384
<li>
 
385
<a href="#stopping">Pausing and stopping an AsyncQueue</a>
 
386
</li>
 
387
<li>
 
388
<a href="#callbacks">About AsyncQueue callbacks</a>
 
389
</li>
 
390
<li>
 
391
<a href="#defaults">Class- and instance-level callback defaults</a>
 
392
</li>
 
393
<li>
 
394
<a href="#sync">Synchronous mode for callback execution</a>
 
395
</li>
 
396
<li>
 
397
<a href="#chaining">About timeout chaining</a>
 
398
</li>
 
399
<li>
 
400
<a href="#events">Exposed events</a>
 
401
</li>
 
402
</ul>
 
403
</li>
 
404
</ul>
 
405
</li>
 
406
</ul>
 
407
                        </div>
 
408
                    </div>
 
409
                
 
410
 
 
411
                
 
412
                    <div class="sidebox">
 
413
                        <div class="hd">
 
414
                            <h2 class="no-toc">Examples</h2>
 
415
                        </div>
 
416
 
 
417
                        <div class="bd">
 
418
                            <ul class="examples">
 
419
                                
 
420
                                    
 
421
                                        <li data-description="This example employs AsyncQueue to incrementally construct an application interface; this illustrates the approach you&#x27;d take to allow chunked rendering of the UI in a process-intensive application.">
 
422
                                            <a href="queue-app.html">Building a UI with AsyncQueue</a>
 
423
                                        </li>
 
424
                                    
 
425
                                
 
426
                            </ul>
 
427
                        </div>
 
428
                    </div>
 
429
                
 
430
 
 
431
                
 
432
            </div>
 
433
        </div>
 
434
    </div>
 
435
</div>
 
436
 
 
437
<script src="../assets/vendor/prettify/prettify-min.js"></script>
 
438
<script>prettyPrint();</script>
 
439
 
 
440
</body>
 
441
</html>