1 <?xml version=
"1.0" encoding=
"utf-8" ?>
2 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4 <html xmlns=
"http://www.w3.org/1999/xhtml" xml:
lang=
"en" lang=
"en">
6 <meta http-equiv=
"Content-Type" content=
"text/html; charset=utf-8" />
7 <meta name=
"generator" content=
"Docutils 0.4: http://docutils.sourceforge.net/" />
8 <title>MochiKit.Async - manage asynchronous tasks
</title>
10 <link rel=
"stylesheet" href=
"../../../include/css/documentation.css" type=
"text/css" />
11 <script type=
"text/javascript" src=
"../../../packed/MochiKit/MochiKit.js"></script>
12 <script type=
"text/javascript" src=
"../../js/toc.js"></script>
15 <div class=
"document">
17 <h1><a id=
"name" name=
"name">Name
</a></h1>
18 <p>MochiKit.Async - manage asynchronous tasks
</p>
21 <h1><a id=
"synopsis" name=
"synopsis">Synopsis
</a></h1>
22 <pre class=
"literal-block">
23 var url =
"/src/b/bo/bob/MochiKit.Async/META.json
";
26 META.json looks something like this:
28 {
"name
":
"MochiKit
",
"version
":
"0.5"}
31 var d = loadJSONDoc(url);
32 var gotMetadata = function (meta) {
33 if (MochiKit.Async.VERSION == meta.version) {
34 alert(
"You have the newest MochiKit.Async!
");
36 alert(
"MochiKit.Async
"
38 +
" is available, upgrade!
");
41 var metadataFetchFailed = function (err) {
42 alert(
"The metadata for MochiKit.Async could not be fetched :(
");
44 d.addCallbacks(gotMetadata, metadataFetchFailed);
48 <h1><a id=
"description" name=
"description">Description
</a></h1>
49 <p>MochiKit.Async provides facilities to manage asynchronous (as in AJAX
50 <a class=
"footnote-reference" href=
"#id7" id=
"id1" name=
"id1">[
1]
</a>) tasks. The model for asynchronous computation used in this
51 module is heavily inspired by Twisted
<a class=
"footnote-reference" href=
"#id8" id=
"id2" name=
"id2">[
2]
</a>.
</p>
54 <h1><a id=
"dependencies" name=
"dependencies">Dependencies
</a></h1>
56 <li><a class=
"mochiref reference" href=
"Base.html">MochiKit.Base
</a></li>
60 <h1><a id=
"overview" name=
"overview">Overview
</a></h1>
62 <h2><a id=
"deferred" name=
"deferred">Deferred
</a></h2>
63 <p>The Deferred constructor encapsulates a single value that is not
64 available yet. The most important example of this in the context of a
65 web browser would be an
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> to a server. The importance
66 of the Deferred is that it allows a consistent API to be exposed for
67 all asynchronous computations that occur exactly once.
</p>
68 <p>The producer of the Deferred is responsible for doing all of the
69 complicated work behind the scenes. This often means waiting for a
70 timer to fire, or waiting for an event (e.g.
<tt class=
"docutils literal"><span class=
"pre">onreadystatechange
</span></tt> of
71 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt>). It could also be coordinating several events
72 (e.g.
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> with a timeout, or several Deferreds
73 (e.g. fetching a set of XML documents that should be processed at the
75 <p>Since these sorts of tasks do not respond immediately, the producer of
76 the Deferred does the following steps before returning to the
78 <ol class=
"arabic simple">
79 <li>Create a
<tt class=
"docutils literal"><span class=
"pre">new
</span></tt> <a class=
"mochiref reference" href=
"#fn-deferred">Deferred();
</a> object and keep a
80 reference to it, because it will be needed later when the value is
82 <li>Setup the conditions to create the value requested (e.g. create a
83 new
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt>, set its
<tt class=
"docutils literal"><span class=
"pre">onreadystatechange
</span></tt>).
</li>
84 <li>Return the
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> object.
</li>
86 <p>Since the value is not yet ready, the consumer attaches a function to
87 the Deferred that will be called when the value is ready. This is not
88 unlike
<tt class=
"docutils literal"><span class=
"pre">setTimeout
</span></tt>, or other similar facilities you may already be
89 familiar with. The consumer can also attach an
"errback
" to the
90 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>, which is a callback for error handling.
</p>
91 <p>When the value is ready, the producer simply calls
92 <tt class=
"docutils literal"><span class=
"pre">myDeferred.callback(theValue)
</span></tt>. If an error occurred, it should
93 call
<tt class=
"docutils literal"><span class=
"pre">myDeferred.errback(theValue)
</span></tt> instead. As soon as this
94 happens, the callback that the consumer attached to the
95 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> is called with
<tt class=
"docutils literal"><span class=
"pre">theValue
</span></tt> as the only argument.
</p>
96 <p>There are quite a few additional
"advanced
" features baked into
97 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>, such as cancellation and callback chains, so
98 take a look at the API reference if you would like to know more!
</p>
101 <div class=
"section">
102 <h1><a id=
"api-reference" name=
"api-reference">API Reference
</a></h1>
103 <div class=
"section">
104 <h2><a id=
"errors" name=
"errors">Errors
</a></h2>
106 <a name=
"fn-alreadycallederror"></a>
107 <a class=
"mochidef reference" href=
"#fn-alreadycallederror">AlreadyCalledError
</a>:
</p>
109 <p>Thrown by a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> if
<tt class=
"docutils literal"><span class=
"pre">.callback
</span></tt> or
<tt class=
"docutils literal"><span class=
"pre">.errback
</span></tt>
110 are called more than once.
</p>
111 <dl class=
"docutils">
112 <dt><em>Availability
</em>:
</dt>
113 <dd>Available in MochiKit
1.3.1+
</dd>
117 <a name=
"fn-browsercomplianceerror"></a>
118 <a class=
"mochidef reference" href=
"#fn-browsercomplianceerror">BrowserComplianceError
</a>:
</p>
120 <p>Thrown when the JavaScript runtime is not capable of performing
121 the given function. Currently, this happens if the browser does
122 not support
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt>.
</p>
123 <dl class=
"docutils">
124 <dt><em>Availability
</em>:
</dt>
125 <dd>Available in MochiKit
1.3.1+
</dd>
129 <a name=
"fn-cancellederror"></a>
130 <a class=
"mochidef reference" href=
"#fn-cancellederror">CancelledError
</a>:
</p>
132 <p>Thrown by a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> when it is cancelled, unless a
133 canceller is present and throws something else.
</p>
134 <dl class=
"docutils">
135 <dt><em>Availability
</em>:
</dt>
136 <dd>Available in MochiKit
1.3.1+
</dd>
140 <a name=
"fn-genericerror"></a>
141 <a class=
"mochidef reference" href=
"#fn-genericerror">GenericError
</a>:
</p>
143 <p>Results passed to
<tt class=
"docutils literal"><span class=
"pre">.fail
</span></tt> or
<tt class=
"docutils literal"><span class=
"pre">.errback
</span></tt> of a
144 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> are wrapped by this
<tt class=
"docutils literal"><span class=
"pre">Error
</span></tt> if
<tt class=
"docutils literal"><span class=
"pre">!(result
</span>
145 <span class=
"pre">instanceof
</span> <span class=
"pre">Error)
</span></tt>.
</p>
146 <dl class=
"docutils">
147 <dt><em>Availability
</em>:
</dt>
148 <dd>Available in MochiKit
1.3.1+
</dd>
152 <a name=
"fn-xmlhttprequesterror"></a>
153 <a class=
"mochidef reference" href=
"#fn-xmlhttprequesterror">XMLHttpRequestError
</a>:
</p>
155 <p>Thrown when an
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> does not complete successfully
156 for any reason. The
<tt class=
"docutils literal"><span class=
"pre">req
</span></tt> property of the error is the failed
157 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> object, and for convenience the
<tt class=
"docutils literal"><span class=
"pre">number
</span></tt>
158 property corresponds to
<tt class=
"docutils literal"><span class=
"pre">req.status
</span></tt>.
</p>
159 <dl class=
"docutils">
160 <dt><em>Availability
</em>:
</dt>
161 <dd>Available in MochiKit
1.3.1+
</dd>
165 <div class=
"section">
166 <h2><a id=
"constructors" name=
"constructors">Constructors
</a></h2>
168 <a name=
"fn-deferred"></a>
169 <a class=
"mochidef reference" href=
"#fn-deferred">Deferred()
</a>:
</p>
171 Encapsulates a sequence of callbacks in response to a value that
172 may not yet be available. This is modeled after the Deferred class
173 from Twisted
<a class=
"footnote-reference" href=
"#id9" id=
"id3" name=
"id3">[
3]
</a>.
</blockquote>
175 <p>Why do we want this? JavaScript has no threads, and even if it
176 did, threads are hard. Deferreds are a way of abstracting
177 non-blocking events, such as the final response to an
178 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt>.
</p>
179 <p>The sequence of callbacks is internally represented as a list of
180 2-tuples containing the callback/errback pair. For example, the
181 following call sequence:
</p>
182 <pre class=
"literal-block">
183 var d = new Deferred();
184 d.addCallback(myCallback);
185 d.addErrback(myErrback);
187 d.addCallbacks(myCallback, myErrback);
189 <p>is translated into a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> with the following
190 internal representation:
</p>
191 <pre class=
"literal-block">
196 [myCallback, myErrback]
199 <p>The
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> also keeps track of its current status
200 (fired). Its status may be one of the following three values:
</p>
202 <table border=
"1" class=
"docutils">
207 <thead valign=
"bottom">
208 <tr><th class=
"head">Value
</th>
209 <th class=
"head">Condition
</th>
214 <td>no value yet (initial condition)
</td>
225 <p>A
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> will be in the error state if one of the
226 following conditions are met:
</p>
227 <ol class=
"arabic simple">
228 <li>The result given to callback or errback is
"<tt class=
"docutils literal"><span class=
"pre">instanceof
</span>
229 <span class=
"pre">Error
</span></tt>"</li>
230 <li>The callback or errback threw while executing. If the thrown
231 object is not
<tt class=
"docutils literal"><span class=
"pre">instanceof
</span> <span class=
"pre">Error
</span></tt>, it will be wrapped with
232 <a class=
"mochiref reference" href=
"#fn-genericerror">GenericError
</a>.
</li>
234 <p>Otherwise, the
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> will be in the success
235 state. The state of the
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> determines the next
236 element in the callback sequence to run.
</p>
237 <p>When a callback or errback occurs with the example deferred chain,
238 something equivalent to the following will happen (imagine that
239 exceptions are caught and returned as-is):
</p>
240 <pre class=
"literal-block">
241 // d.callback(result) or d.errback(result)
242 if (!(result instanceof Error)) {
243 result = myCallback(result);
245 if (result instanceof Error) {
246 result = myErrback(result);
248 result = myBoth(result);
249 if (result instanceof Error) {
250 result = myErrback(result);
252 result = myCallback(result);
255 <p>The result is then stored away in case another step is added to
256 the callback sequence. Since the
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> already has
257 a value available, any new callbacks added will be called
259 <p>There are two other
"advanced
" details about this implementation
261 <p>Callbacks are allowed to return
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> instances, so
262 you can build complicated sequences of events with (relative)
264 <p>The creator of the
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> may specify a
265 canceller. The canceller is a function that will be called if
266 <a class=
"mochiref reference" href=
"#fn-deferred.prototype.cancel">Deferred.prototype.cancel
</a> is called before the
267 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> fires. You can use this to allow an
268 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> to be cleanly cancelled, for example. Note that
269 cancel will fire the
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> with a
270 <a class=
"mochiref reference" href=
"#fn-cancellederror">CancelledError
</a> (unless your canceller throws or
271 returns a different
<tt class=
"docutils literal"><span class=
"pre">Error
</span></tt>), so errbacks should be prepared to
272 handle that
<tt class=
"docutils literal"><span class=
"pre">Error
</span></tt> gracefully for cancellable
273 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> instances.
</p>
274 <dl class=
"docutils">
275 <dt><em>Availability
</em>:
</dt>
276 <dd>Available in MochiKit
1.3.1+
</dd>
280 <a name=
"fn-deferred.prototype.addboth"></a>
281 <a class=
"mochidef reference" href=
"#fn-deferred.prototype.addboth">Deferred.prototype.addBoth(func)
</a>:
</p>
283 <p>Add the same function as both a callback and an errback as the
284 next element on the callback sequence. This is useful for code
285 that you want to guarantee to run, e.g. a finalizer.
</p>
286 <p>If additional arguments are given, then
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt> will be replaced
287 with
<a class=
"mochiref reference" href=
"Base.html#fn-partial">MochiKit.Base.partial.apply(null,
288 arguments)
</a>. This differs from
<a class=
"reference" href=
"http://twistedmatrix.com/">Twisted
</a>, because the result of
289 the callback or errback will be the
<em>last
</em> argument passed to
290 <tt class=
"docutils literal"><span class=
"pre">func
</span></tt>.
</p>
291 <p>If
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt> returns a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>, then it will be
292 chained (its value or error will be passed to the next
293 callback). Note that once the returned
<tt class=
"docutils literal"><span class=
"pre">Deferred
</span></tt> is chained, it
294 can no longer accept new callbacks.
</p>
295 <dl class=
"docutils">
296 <dt><em>Availability
</em>:
</dt>
297 <dd>Available in MochiKit
1.3.1+
</dd>
301 <a name=
"fn-deferred.prototype.addcallback"></a>
302 <a class=
"mochidef reference" href=
"#fn-deferred.prototype.addcallback">Deferred.prototype.addCallback(func[, ...])
</a>:
</p>
304 <p>Add a single callback to the end of the callback sequence.
</p>
305 <p>If additional arguments are given, then
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt> will be replaced
306 with
<a class=
"mochiref reference" href=
"Base.html#fn-partial">MochiKit.Base.partial.apply(null,
307 arguments)
</a>. This differs from
<a class=
"reference" href=
"http://twistedmatrix.com/">Twisted
</a>, because the result of
308 the callback will be the
<em>last
</em> argument passed to
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt>.
</p>
309 <p>If
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt> returns a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>, then it will be
310 chained (its value or error will be passed to the next
311 callback). Note that once the returned
<tt class=
"docutils literal"><span class=
"pre">Deferred
</span></tt> is chained, it
312 can no longer accept new callbacks.
</p>
313 <dl class=
"docutils">
314 <dt><em>Availability
</em>:
</dt>
315 <dd>Available in MochiKit
1.3.1+
</dd>
319 <a name=
"fn-deferred.prototype.addcallbacks"></a>
320 <a class=
"mochidef reference" href=
"#fn-deferred.prototype.addcallbacks">Deferred.prototype.addCallbacks(callback, errback)
</a>:
</p>
322 <p>Add separate callback and errback to the end of the callback
323 sequence. Either callback or errback may be
<tt class=
"docutils literal"><span class=
"pre">null
</span></tt>, but not
325 <p>If
<tt class=
"docutils literal"><span class=
"pre">callback
</span></tt> or
<tt class=
"docutils literal"><span class=
"pre">errback
</span></tt> returns a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>,
326 then it will be chained (its value or error will be passed to the
327 next callback). Note that once the returned
<tt class=
"docutils literal"><span class=
"pre">Deferred
</span></tt> is
328 chained, it can no longer accept new callbacks.
</p>
329 <dl class=
"docutils">
330 <dt><em>Availability
</em>:
</dt>
331 <dd>Available in MochiKit
1.3.1+
</dd>
335 <a name=
"fn-deferred.prototype.adderrback"></a>
336 <a class=
"mochidef reference" href=
"#fn-deferred.prototype.adderrback">Deferred.prototype.addErrback(func)
</a>:
</p>
338 <p>Add a single errback to the end of the callback sequence.
</p>
339 <p>If additional arguments are given, then
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt> will be replaced
340 with
<a class=
"mochiref reference" href=
"Base.html#fn-partial">MochiKit.Base.partial.apply(null,
341 arguments)
</a>. This differs from
<a class=
"reference" href=
"http://twistedmatrix.com/">Twisted
</a>, because the result of
342 the errback will be the
<em>last
</em> argument passed to
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt>.
</p>
343 <p>If
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt> returns a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>, then it will be
344 chained (its value or error will be passed to the next
345 callback). Note that once the returned
<tt class=
"docutils literal"><span class=
"pre">Deferred
</span></tt> is chained, it
346 can no longer accept new callbacks.
</p>
347 <dl class=
"docutils">
348 <dt><em>Availability
</em>:
</dt>
349 <dd>Available in MochiKit
1.3.1+
</dd>
353 <a name=
"fn-deferred.prototype.callback"></a>
354 <a class=
"mochidef reference" href=
"#fn-deferred.prototype.callback">Deferred.prototype.callback([result])
</a>:
</p>
356 <p>Begin the callback sequence with a non-
<tt class=
"docutils literal"><span class=
"pre">Error
</span></tt> result. Result
357 may be any value except for a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>.
</p>
358 <p>Either
<tt class=
"docutils literal"><span class=
"pre">.callback
</span></tt> or
<tt class=
"docutils literal"><span class=
"pre">.errback
</span></tt> should be called exactly once
359 on a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>.
</p>
360 <dl class=
"docutils">
361 <dt><em>Availability
</em>:
</dt>
362 <dd>Available in MochiKit
1.3.1+
</dd>
366 <a name=
"fn-deferred.prototype.cancel"></a>
367 <a class=
"mochidef reference" href=
"#fn-deferred.prototype.cancel">Deferred.prototype.cancel()
</a>:
</p>
369 <p>Cancels a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that has not yet received a value,
370 or is waiting on another
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> as its value.
</p>
371 <p>If a canceller is defined, the canceller is called. If the
372 canceller did not return an
<tt class=
"docutils literal"><span class=
"pre">Error
</span></tt>, or there was no canceller,
373 then the errback chain is started with
<a class=
"mochiref reference" href=
"#fn-cancellederror">CancelledError
</a>.
</p>
374 <dl class=
"docutils">
375 <dt><em>Availability
</em>:
</dt>
376 <dd>Available in MochiKit
1.3.1+
</dd>
380 <a name=
"fn-deferred.prototype.errback"></a>
381 <a class=
"mochidef reference" href=
"#fn-deferred.prototype.errback">Deferred.prototype.errback([result])
</a>:
</p>
383 <p>Begin the callback sequence with an error result. Result may be
384 any value except for a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>, but if
<tt class=
"docutils literal"><span class=
"pre">!(result
</span>
385 <span class=
"pre">instanceof
</span> <span class=
"pre">Error)
</span></tt>, it will be wrapped with
386 <a class=
"mochiref reference" href=
"#fn-genericerror">GenericError
</a>.
</p>
387 <p>Either
<tt class=
"docutils literal"><span class=
"pre">.callback
</span></tt> or
<tt class=
"docutils literal"><span class=
"pre">.errback
</span></tt> should be called exactly once
389 <a name=
"fn-deferred"></a>
390 <a class=
"mochidef reference" href=
"#fn-deferred">Deferred
</a>.
</p>
391 <dl class=
"docutils">
392 <dt><em>Availability
</em>:
</dt>
393 <dd>Available in MochiKit
1.3.1+
</dd>
397 <a name=
"fn-deferredlock"></a>
398 <a class=
"mochidef reference" href=
"#fn-deferredlock">DeferredLock()
</a>:
</p>
400 <p>A lock for asynchronous systems.
</p>
401 <p>The
<tt class=
"docutils literal"><span class=
"pre">locked
</span></tt> property of a
<a class=
"mochiref reference" href=
"#fn-deferredlock">DeferredLock
</a> will be
402 <tt class=
"docutils literal"><span class=
"pre">true
</span></tt> if it locked,
<tt class=
"docutils literal"><span class=
"pre">false
</span></tt> otherwise. Do not change this
404 <dl class=
"docutils">
405 <dt><em>Availability
</em>:
</dt>
406 <dd>Available in MochiKit
1.3.1+
</dd>
410 <a name=
"fn-deferredlock.prototype.acquire"></a>
411 <a class=
"mochidef reference" href=
"#fn-deferredlock.prototype.acquire">DeferredLock.prototype.acquire()
</a>:
</p>
413 <p>Attempt to acquire the lock. Returns a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that
414 fires on lock acquisition with the
<a class=
"mochiref reference" href=
"#fn-deferredlock">DeferredLock
</a> as the
415 value. If the lock is locked, then the
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> goes
416 into a waiting list.
</p>
417 <dl class=
"docutils">
418 <dt><em>Availability
</em>:
</dt>
419 <dd>Available in MochiKit
1.3.1+
</dd>
423 <a name=
"fn-deferredlock.prototype.release"></a>
424 <a class=
"mochidef reference" href=
"#fn-deferredlock.prototype.release">DeferredLock.prototype.release()
</a>:
</p>
426 <p>Release the lock. If there is a waiting list, then the first
427 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> in that waiting list will be called back.
</p>
428 <dl class=
"docutils">
429 <dt><em>Availability
</em>:
</dt>
430 <dd>Available in MochiKit
1.3.1+
</dd>
434 <a name=
"fn-deferredlist"></a>
435 <a class=
"mochidef reference" href=
"#fn-deferredlist">DeferredList(list, [fireOnOneCallback, fireOnOneErrback, consumeErrors, canceller])
</a>:
</p>
437 <p>Combine a list of
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> into one. Track the
438 callbacks and return a list of (success, result) tuples, 'success'
439 being a boolean indicating whether result is a normal result or an
441 <p>Once created, you have access to all
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> methods,
442 like addCallback, addErrback, addBoth. The behaviour can be
443 changed by the following options:
</p>
444 <dl class=
"docutils">
445 <dt><tt class=
"docutils literal"><span class=
"pre">fireOnOneCallback
</span></tt>:
</dt>
446 <dd>Flag for launching the callback once the first Deferred of the
447 list has returned.
</dd>
448 <dt><tt class=
"docutils literal"><span class=
"pre">fireOnOneErrback
</span></tt>:
</dt>
449 <dd>Flag for calling the errback at the first error of a Deferred.
</dd>
450 <dt><tt class=
"docutils literal"><span class=
"pre">consumeErrors
</span></tt>:
</dt>
451 <dd>Flag indicating that any errors raised in the Deferreds should
452 be consumed by the DeferredList.
</dd>
455 <pre class=
"literal-block">
456 // We need to fetch data from
2 different urls
457 var d1 = loadJSONDoc(url1);
458 var d2 = loadJSONDoc(url2);
459 var l1 = new DeferredList([d1, d2], false, false, true);
460 l1.addCallback(function (resultList) {
461 MochiKit.Base.map(function (result) {
463 alert(
"Data is here:
" + result[
1]);
465 alert(
"Got an error:
" + result[
1]);
470 <dl class=
"docutils">
471 <dt><em>Availability
</em>:
</dt>
472 <dd>Available in MochiKit
1.3.1+
</dd>
476 <div class=
"section">
477 <h2><a id=
"functions" name=
"functions">Functions
</a></h2>
479 <a name=
"fn-calllater"></a>
480 <a class=
"mochidef reference" href=
"#fn-calllater">callLater(seconds, func[, args...])
</a>:
</p>
482 <p>Call
<tt class=
"docutils literal"><span class=
"pre">func(args...)
</span></tt> after at least
<tt class=
"docutils literal"><span class=
"pre">seconds
</span></tt> seconds have
483 elapsed. This is a convenience method for:
</p>
484 <pre class=
"literal-block">
485 func = partial.apply(extend(null, arguments,
1));
486 return wait(seconds).addCallback(function (res) { return func() });
488 <p>Returns a cancellable
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>.
</p>
489 <dl class=
"docutils">
490 <dt><em>Availability
</em>:
</dt>
491 <dd>Available in MochiKit
1.3.1+
</dd>
495 <a name=
"fn-doxhr"></a>
496 <a class=
"mochidef reference" href=
"#fn-doxhr">doXHR(url[, {option: value, ...}])
</a>:
</p>
498 <p>Perform a customized
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> and wrap it with a
499 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that may be cancelled.
</p>
500 <p>Note that only
<tt class=
"docutils literal"><span class=
"pre">200</span></tt> (OK),
<tt class=
"docutils literal"><span class=
"pre">201</span></tt> (CREATED),
501 <tt class=
"docutils literal"><span class=
"pre">204</span></tt> (NO CONTENT) and
<tt class=
"docutils literal"><span class=
"pre">304</span></tt> (NOT MODIFIED) are considered
502 success codes. All other status codes will
503 result in an errback with an
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequestError
</span></tt>.
</p>
504 <dl class=
"docutils">
505 <dt><tt class=
"docutils literal"><span class=
"pre">url
</span></tt>:
</dt>
506 <dd>The URL for this request.
</dd>
508 <p>The following options are currently accepted:
</p>
509 <dl class=
"docutils">
510 <dt><tt class=
"docutils literal"><span class=
"pre">method
</span></tt>:
</dt>
511 <dd>The HTTP method. Default is
<tt class=
"docutils literal"><span class=
"pre">'GET'
</span></tt>.
</dd>
512 <dt><tt class=
"docutils literal"><span class=
"pre">sendContent
</span></tt>:
</dt>
513 <dd>The content to send (e.g. with POST). Default is no content.
</dd>
514 <dt><tt class=
"docutils literal"><span class=
"pre">queryString
</span></tt>:
</dt>
515 <dd>If present it will be used to build a query string to append to
516 the url using
<a class=
"mochiref reference" href=
"Base.html#fn-querystring">MochiKit.Base.queryString
</a>. Default is
517 no query string.
</dd>
518 <dt><tt class=
"docutils literal"><span class=
"pre">username
</span></tt>:
</dt>
519 <dd>The username for the request. Default is no username.
</dd>
520 <dt><tt class=
"docutils literal"><span class=
"pre">password
</span></tt>:
</dt>
521 <dd>The password for the request. Default is no password.
</dd>
522 <dt><tt class=
"docutils literal"><span class=
"pre">headers
</span></tt>:
</dt>
523 <dd>Additional headers to set in the request, either as an object
524 such as
<tt class=
"docutils literal"><span class=
"pre">{'Accept':
</span> <span class=
"pre">'text/xml'}
</span></tt> or as an Array of
2-Arrays
525 <tt class=
"docutils literal"><span class=
"pre">[['Accept',
</span> <span class=
"pre">'text/xml']]
</span></tt>. Default is no additional headers.
</dd>
526 <dt><tt class=
"docutils literal"><span class=
"pre">mimeType
</span></tt>:
</dt>
527 <dd>An override mime type. The typical use of this is to pass
528 'text/xml' to force XMLHttpRequest to attempt to parse responseXML.
529 Default is no override.
</dd>
530 <dt><em>returns
</em>:
</dt>
531 <dd><a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that will callback with the
532 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> instance on success
</dd>
533 <dt><em>Availability
</em>:
</dt>
534 <dd>Available in MochiKit
1.4+.
</dd>
538 <a name=
"fn-dosimplexmlhttprequest"></a>
539 <a class=
"mochidef reference" href=
"#fn-dosimplexmlhttprequest">doSimpleXMLHttpRequest(url[, queryArguments...])
</a>:
</p>
541 <p>Perform a simple
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> and wrap it with a
542 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that may be cancelled.
</p>
543 <p>Note that only
<tt class=
"docutils literal"><span class=
"pre">200</span></tt> (OK),
<tt class=
"docutils literal"><span class=
"pre">201</span></tt> (CREATED),
544 <tt class=
"docutils literal"><span class=
"pre">204</span></tt> (NO CONTENT) and
<tt class=
"docutils literal"><span class=
"pre">304</span></tt> (NOT MODIFIED) are considered
545 success codes. All other status codes will
546 result in an errback with an
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequestError
</span></tt>.
</p>
547 <dl class=
"docutils">
548 <dt><tt class=
"docutils literal"><span class=
"pre">url
</span></tt>:
</dt>
549 <dd>The URL to GET
</dd>
550 <dt><tt class=
"docutils literal"><span class=
"pre">queryArguments
</span></tt>:
</dt>
551 <dd><p class=
"first">If this function is called with more than one argument, a
552 <tt class=
"docutils literal"><span class=
"pre">"?
"</span></tt> and the result of
553 <a class=
"mochiref reference" href=
"Base.html#fn-querystring">MochiKit.Base.queryString
</a> with the rest of the
554 arguments are appended to the URL.
</p>
555 <p>For example, this will do a GET request to the URL
556 <tt class=
"docutils literal"><span class=
"pre">http://example.com?bar=baz
</span></tt>:
</p>
557 <pre class=
"last literal-block">
558 doSimpleXMLHttpRequest(
"http://example.com
", {bar:
"baz
"});
561 <dt><em>returns
</em>:
</dt>
562 <dd><a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that will callback with the
563 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> instance on success
</dd>
564 <dt><em>Availability
</em>:
</dt>
565 <dd>Available in MochiKit
1.3.1+. Support for
201 and
204 were added in
570 <a name=
"fn-evaljsonrequest"></a>
571 <a class=
"mochidef reference" href=
"#fn-evaljsonrequest">evalJSONRequest(req)
</a>:
</p>
573 <p>Evaluate a JSON
<a class=
"footnote-reference" href=
"#id10" id=
"id4" name=
"id4">[
4]
</a> <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt></p>
574 <dl class=
"docutils">
575 <dt><tt class=
"docutils literal"><span class=
"pre">req
</span></tt>:
</dt>
576 <dd>The request whose
<tt class=
"docutils literal"><span class=
"pre">.responseText
</span></tt> property is to be
578 <dt><em>returns
</em>:
</dt>
579 <dd>A JavaScript object
</dd>
580 <dt><em>Availability
</em>:
</dt>
581 <dd>Available in MochiKit
1.3.1+
</dd>
585 <a name=
"fn-fail"></a>
586 <a class=
"mochidef reference" href=
"#fn-fail">fail([result])
</a>:
</p>
588 <p>Return a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that has already had
589 <tt class=
"docutils literal"><span class=
"pre">.errback(result)
</span></tt> called.
</p>
590 <p>See
<tt class=
"docutils literal"><span class=
"pre">succeed
</span></tt> documentation for rationale.
</p>
591 <dl class=
"docutils">
592 <dt><tt class=
"docutils literal"><span class=
"pre">result
</span></tt>:
</dt>
593 <dd>The result to give to
594 <a class=
"mochiref reference" href=
"#fn-deferred.prototype.errback">Deferred.prototype.errback(result)
</a>.
</dd>
595 <dt><em>returns
</em>:
</dt>
596 <dd>A
<tt class=
"docutils literal"><span class=
"pre">new
</span></tt> <a class=
"mochiref reference" href=
"#fn-deferred">Deferred()
</a></dd>
597 <dt><em>Availability
</em>:
</dt>
598 <dd>Available in MochiKit
1.3.1+
</dd>
602 <a name=
"fn-gatherresults"></a>
603 <a class=
"mochidef reference" href=
"#fn-gatherresults">gatherResults(deferreds)
</a>:
</p>
605 <p>A convenience function that returns a
<a class=
"mochiref reference" href=
"#fn-deferredlist">DeferredList
</a>
606 from the given
<tt class=
"docutils literal"><span class=
"pre">Array
</span></tt> of
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> instances that
607 will callback with an
<tt class=
"docutils literal"><span class=
"pre">Array
</span></tt> of just results when they're
608 available, or errback on the first array.
</p>
609 <dl class=
"docutils">
610 <dt><em>Availability
</em>:
</dt>
611 <dd>Available in MochiKit
1.3.1+
</dd>
615 <a name=
"fn-getxmlhttprequest"></a>
616 <a class=
"mochidef reference" href=
"#fn-getxmlhttprequest">getXMLHttpRequest()
</a>:
</p>
618 <p>Return an
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> compliant object for the current
620 <p>In order of preference:
</p>
622 <li><tt class=
"docutils literal"><span class=
"pre">new
</span> <span class=
"pre">XMLHttpRequest()
</span></tt></li>
623 <li><tt class=
"docutils literal"><span class=
"pre">new
</span> <span class=
"pre">ActiveXObject('Msxml2.XMLHTTP')
</span></tt></li>
624 <li><tt class=
"docutils literal"><span class=
"pre">new
</span> <span class=
"pre">ActiveXObject('Microsoft.XMLHTTP')
</span></tt></li>
625 <li><tt class=
"docutils literal"><span class=
"pre">new
</span> <span class=
"pre">ActiveXObject('Msxml2.XMLHTTP
.4.0')
</span></tt></li>
627 <dl class=
"docutils">
628 <dt><em>Availability
</em>:
</dt>
629 <dd>Available in MochiKit
1.3.1+
</dd>
633 <a name=
"fn-maybedeferred"></a>
634 <a class=
"mochidef reference" href=
"#fn-maybedeferred">maybeDeferred(func[, argument...])
</a>:
</p>
636 <p>Call a
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt> with the given arguments and ensure the result is
637 a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>.
</p>
638 <dl class=
"docutils">
639 <dt><tt class=
"docutils literal"><span class=
"pre">func
</span></tt>:
</dt>
640 <dd>The function to call.
</dd>
641 <dt><em>returns
</em>:
</dt>
642 <dd>A new
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> based on the call to
<tt class=
"docutils literal"><span class=
"pre">func
</span></tt>. If
643 <tt class=
"docutils literal"><span class=
"pre">func
</span></tt> does not naturally return a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a>, its
644 result or error value will be wrapped by one.
</dd>
645 <dt><em>Availability
</em>:
</dt>
646 <dd>Available in MochiKit
1.3.1+
</dd>
650 <a name=
"fn-loadjsondoc"></a>
651 <a class=
"mochidef reference" href=
"#fn-loadjsondoc">loadJSONDoc(url[, queryArguments...])
</a>:
</p>
653 <p>Do a simple
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> to a URL and get the response as a
654 JSON
<a class=
"footnote-reference" href=
"#id10" id=
"id5" name=
"id5">[
4]
</a> document.
</p>
655 <dl class=
"docutils">
656 <dt><tt class=
"docutils literal"><span class=
"pre">url
</span></tt>:
</dt>
657 <dd>The URL to GET
</dd>
658 <dt><tt class=
"docutils literal"><span class=
"pre">queryArguments
</span></tt>:
</dt>
659 <dd><p class=
"first">If this function is called with more than one argument, a
660 <tt class=
"docutils literal"><span class=
"pre">"?
"</span></tt> and the result of
661 <a class=
"mochiref reference" href=
"Base.html#fn-querystring">MochiKit.Base.queryString
</a> with the rest of the
662 arguments are appended to the URL.
</p>
663 <p>For example, this will do a GET request to the URL
664 <tt class=
"docutils literal"><span class=
"pre">http://example.com?bar=baz
</span></tt>:
</p>
665 <pre class=
"last literal-block">
666 loadJSONDoc(
"http://example.com
", {bar:
"baz
"});
669 <dt><em>returns
</em>:
</dt>
670 <dd><a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that will callback with the evaluated
671 JSON
<a class=
"footnote-reference" href=
"#id10" id=
"id6" name=
"id6">[
4]
</a> response upon successful
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt></dd>
672 <dt><em>Availability
</em>:
</dt>
673 <dd>Available in MochiKit
1.3.1+
</dd>
677 <a name=
"fn-sendxmlhttprequest"></a>
678 <a class=
"mochidef reference" href=
"#fn-sendxmlhttprequest">sendXMLHttpRequest(req[, sendContent])
</a>:
</p>
680 <p>Set an
<tt class=
"docutils literal"><span class=
"pre">onreadystatechange
</span></tt> handler on an
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt>
681 object and send it off. Will return a cancellable
682 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that will callback on success.
</p>
683 <p>Note that only
<tt class=
"docutils literal"><span class=
"pre">200</span></tt> (OK),
<tt class=
"docutils literal"><span class=
"pre">201</span></tt> (CREATED),
684 <tt class=
"docutils literal"><span class=
"pre">204</span></tt> (NO CONTENT) and
<tt class=
"docutils literal"><span class=
"pre">304</span></tt> (NOT MODIFIED) are considered
685 success codes. All other status codes will
686 result in an errback with an
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequestError
</span></tt>.
</p>
687 <dl class=
"docutils">
688 <dt><tt class=
"docutils literal"><span class=
"pre">req
</span></tt>:
</dt>
689 <dd>An preconfigured
<tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> object (open has been
691 <dt><tt class=
"docutils literal"><span class=
"pre">sendContent
</span></tt>:
</dt>
692 <dd>Optional string or DOM content to send over the
693 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt>.
</dd>
694 <dt><em>returns
</em>:
</dt>
695 <dd><a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that will callback with the
696 <tt class=
"docutils literal"><span class=
"pre">XMLHttpRequest
</span></tt> instance on success.
</dd>
697 <dt><em>Availability
</em>:
</dt>
698 <dd>Available in MochiKit
1.3.1+. Support for
201 and
204 were added in
703 <a name=
"fn-succeed"></a>
704 <a class=
"mochidef reference" href=
"#fn-succeed">succeed([result])
</a>:
</p>
706 <p>Return a
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that has already had
707 <tt class=
"docutils literal"><span class=
"pre">.callback(result)
</span></tt> called.
</p>
708 <p>This is useful when you're writing synchronous code to an
709 asynchronous interface: i.e., some code is calling you expecting a
710 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> result, but you don't actually need to do
711 anything asynchronous. Just return
<tt class=
"docutils literal"><span class=
"pre">succeed(theResult)
</span></tt>.
</p>
712 <p>See
<tt class=
"docutils literal"><span class=
"pre">fail
</span></tt> for a version of this function that uses a failing
713 <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> rather than a successful one.
</p>
714 <dl class=
"docutils">
715 <dt><tt class=
"docutils literal"><span class=
"pre">result
</span></tt>:
</dt>
716 <dd>The result to give to
717 <a class=
"mochiref reference" href=
"#fn-deferred.prototype.callback">Deferred.prototype.callback(result)
</a></dd>
718 <dt><em>returns
</em>:
</dt>
719 <dd>a
<tt class=
"docutils literal"><span class=
"pre">new
</span></tt> <a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a></dd>
720 <dt><em>Availability
</em>:
</dt>
721 <dd>Available in MochiKit
1.3.1+
</dd>
725 <a name=
"fn-wait"></a>
726 <a class=
"mochidef reference" href=
"#fn-wait">wait(seconds[, res])
</a>:
</p>
728 <p>Return a new cancellable
<a class=
"mochiref reference" href=
"#fn-deferred">Deferred
</a> that will
729 <tt class=
"docutils literal"><span class=
"pre">.callback(res)
</span></tt> after at least
<tt class=
"docutils literal"><span class=
"pre">seconds
</span></tt> seconds have
731 <dl class=
"docutils">
732 <dt><em>Availability
</em>:
</dt>
733 <dd>Available in MochiKit
1.3.1+
</dd>
738 <div class=
"section">
739 <h1><a id=
"see-also" name=
"see-also">See Also
</a></h1>
740 <table class=
"docutils footnote" frame=
"void" id=
"id7" rules=
"none">
741 <colgroup><col class=
"label" /><col /></colgroup>
743 <tr><td class=
"label"><a class=
"fn-backref" href=
"#id1" name=
"id7">[
1]
</a></td><td>AJAX, Asynchronous JavaScript and XML:
<a class=
"reference" href=
"http://en.wikipedia.org/wiki/AJAX">http://en.wikipedia.org/wiki/AJAX
</a></td></tr>
746 <table class=
"docutils footnote" frame=
"void" id=
"id8" rules=
"none">
747 <colgroup><col class=
"label" /><col /></colgroup>
749 <tr><td class=
"label"><a class=
"fn-backref" href=
"#id2" name=
"id8">[
2]
</a></td><td>Twisted, an event-driven networking framework written in Python:
<a class=
"reference" href=
"http://twistedmatrix.com/">http://twistedmatrix.com/
</a></td></tr>
752 <table class=
"docutils footnote" frame=
"void" id=
"id9" rules=
"none">
753 <colgroup><col class=
"label" /><col /></colgroup>
755 <tr><td class=
"label"><a class=
"fn-backref" href=
"#id3" name=
"id9">[
3]
</a></td><td>Twisted Deferred Reference:
<a class=
"reference" href=
"http://twistedmatrix.com/projects/core/documentation/howto/defer.html">http://twistedmatrix.com/projects/core/documentation/howto/defer.html
</a></td></tr>
758 <table class=
"docutils footnote" frame=
"void" id=
"id10" rules=
"none">
759 <colgroup><col class=
"label" /><col /></colgroup>
761 <tr><td class=
"label"><a name=
"id10">[
4]
</a></td><td><em>(
<a class=
"fn-backref" href=
"#id4">1</a>,
<a class=
"fn-backref" href=
"#id5">2</a>,
<a class=
"fn-backref" href=
"#id6">3</a>)
</em> JSON, JavaScript Object Notation:
<a class=
"reference" href=
"http://json.org/">http://json.org/
</a></td></tr>
765 <div class=
"section">
766 <h1><a id=
"authors" name=
"authors">Authors
</a></h1>
768 <li>Bob Ippolito
<<a class=
"reference" href=
"mailto:bob@redivi.com">bob
@redivi.com
</a>></li>
771 <div class=
"section">
772 <h1><a id=
"copyright" name=
"copyright">Copyright
</a></h1>
773 <p>Copyright
2005 Bob Ippolito
<<a class=
"reference" href=
"mailto:bob@redivi.com">bob
@redivi.com
</a>>. This program is
774 dual-licensed free software; you can redistribute it and/or modify it
775 under the terms of the
<a class=
"reference" href=
"http://www.opensource.org/licenses/mit-license.php">MIT License
</a> or the
<a class=
"reference" href=
"http://www.opensource.org/licenses/afl-2.1.php">Academic Free License