| 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"> |
| 3 | |
| 4 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 5 | <head> |
| 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> |
| 9 | |
| 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> |
| 13 | </head> |
| 14 | <body> |
| 15 | <div class="document"> |
| 16 | <div class="section"> |
| 17 | <h1><a id="name" name="name">Name</a></h1> |
| 18 | <p>MochiKit.Async - manage asynchronous tasks</p> |
| 19 | </div> |
| 20 | <div class="section"> |
| 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"; |
| 24 | /* |
| 25 | |
| 26 | META.json looks something like this: |
| 27 | |
| 28 | {"name": "MochiKit", "version": "0.5"} |
| 29 | |
| 30 | */ |
| 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!"); |
| 35 | } else { |
| 36 | alert("MochiKit.Async " |
| 37 | + meta.version |
| 38 | + " is available, upgrade!"); |
| 39 | } |
| 40 | }; |
| 41 | var metadataFetchFailed = function (err) { |
| 42 | alert("The metadata for MochiKit.Async could not be fetched :("); |
| 43 | }; |
| 44 | d.addCallbacks(gotMetadata, metadataFetchFailed); |
| 45 | </pre> |
| 46 | </div> |
| 47 | <div class="section"> |
| 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> |
| 52 | </div> |
| 53 | <div class="section"> |
| 54 | <h1><a id="dependencies" name="dependencies">Dependencies</a></h1> |
| 55 | <ul class="simple"> |
| 56 | <li><a class="mochiref reference" href="Base.html">MochiKit.Base</a></li> |
| 57 | </ul> |
| 58 | </div> |
| 59 | <div class="section"> |
| 60 | <h1><a id="overview" name="overview">Overview</a></h1> |
| 61 | <div class="section"> |
| 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 |
| 74 | same time).</p> |
| 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 |
| 77 | consumer:</p> |
| 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 |
| 81 | ready.</li> |
| 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> |
| 85 | </ol> |
| 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> |
| 99 | </div> |
| 100 | </div> |
| 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> |
| 105 | <p> |
| 106 | <a name="fn-alreadycallederror"></a> |
| 107 | <a class="mochidef reference" href="#fn-alreadycallederror">AlreadyCalledError</a>:</p> |
| 108 | <blockquote> |
| 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> |
| 114 | </dl> |
| 115 | </blockquote> |
| 116 | <p> |
| 117 | <a name="fn-browsercomplianceerror"></a> |
| 118 | <a class="mochidef reference" href="#fn-browsercomplianceerror">BrowserComplianceError</a>:</p> |
| 119 | <blockquote> |
| 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> |
| 126 | </dl> |
| 127 | </blockquote> |
| 128 | <p> |
| 129 | <a name="fn-cancellederror"></a> |
| 130 | <a class="mochidef reference" href="#fn-cancellederror">CancelledError</a>:</p> |
| 131 | <blockquote> |
| 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> |
| 137 | </dl> |
| 138 | </blockquote> |
| 139 | <p> |
| 140 | <a name="fn-genericerror"></a> |
| 141 | <a class="mochidef reference" href="#fn-genericerror">GenericError</a>:</p> |
| 142 | <blockquote> |
| 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> |
| 149 | </dl> |
| 150 | </blockquote> |
| 151 | <p> |
| 152 | <a name="fn-xmlhttprequesterror"></a> |
| 153 | <a class="mochidef reference" href="#fn-xmlhttprequesterror">XMLHttpRequestError</a>:</p> |
| 154 | <blockquote> |
| 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> |
| 162 | </dl> |
| 163 | </blockquote> |
| 164 | </div> |
| 165 | <div class="section"> |
| 166 | <h2><a id="constructors" name="constructors">Constructors</a></h2> |
| 167 | <p> |
| 168 | <a name="fn-deferred"></a> |
| 169 | <a class="mochidef reference" href="#fn-deferred">Deferred()</a>:</p> |
| 170 | <blockquote> |
| 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> |
| 174 | <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); |
| 186 | d.addBoth(myBoth); |
| 187 | d.addCallbacks(myCallback, myErrback); |
| 188 | </pre> |
| 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"> |
| 192 | [ |
| 193 | [myCallback, null], |
| 194 | [null, myErrback], |
| 195 | [myBoth, myBoth], |
| 196 | [myCallback, myErrback] |
| 197 | ] |
| 198 | </pre> |
| 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> |
| 201 | <blockquote> |
| 202 | <table border="1" class="docutils"> |
| 203 | <colgroup> |
| 204 | <col width="14%" /> |
| 205 | <col width="86%" /> |
| 206 | </colgroup> |
| 207 | <thead valign="bottom"> |
| 208 | <tr><th class="head">Value</th> |
| 209 | <th class="head">Condition</th> |
| 210 | </tr> |
| 211 | </thead> |
| 212 | <tbody valign="top"> |
| 213 | <tr><td>-1</td> |
| 214 | <td>no value yet (initial condition)</td> |
| 215 | </tr> |
| 216 | <tr><td>0</td> |
| 217 | <td>success</td> |
| 218 | </tr> |
| 219 | <tr><td>1</td> |
| 220 | <td>error</td> |
| 221 | </tr> |
| 222 | </tbody> |
| 223 | </table> |
| 224 | </blockquote> |
| 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> |
| 233 | </ol> |
| 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); |
| 244 | } |
| 245 | if (result instanceof Error) { |
| 246 | result = myErrback(result); |
| 247 | } |
| 248 | result = myBoth(result); |
| 249 | if (result instanceof Error) { |
| 250 | result = myErrback(result); |
| 251 | } else { |
| 252 | result = myCallback(result); |
| 253 | } |
| 254 | </pre> |
| 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 |
| 258 | immediately.</p> |
| 259 | <p>There are two other "advanced" details about this implementation |
| 260 | that are useful:</p> |
| 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) |
| 263 | ease.</p> |
| 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> |
| 277 | </dl> |
| 278 | </blockquote> |
| 279 | <p> |
| 280 | <a name="fn-deferred.prototype.addboth"></a> |
| 281 | <a class="mochidef reference" href="#fn-deferred.prototype.addboth">Deferred.prototype.addBoth(func)</a>:</p> |
| 282 | <blockquote> |
| 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> |
| 298 | </dl> |
| 299 | </blockquote> |
| 300 | <p> |
| 301 | <a name="fn-deferred.prototype.addcallback"></a> |
| 302 | <a class="mochidef reference" href="#fn-deferred.prototype.addcallback">Deferred.prototype.addCallback(func[, ...])</a>:</p> |
| 303 | <blockquote> |
| 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> |
| 316 | </dl> |
| 317 | </blockquote> |
| 318 | <p> |
| 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> |
| 321 | <blockquote> |
| 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 |
| 324 | both.</p> |
| 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> |
| 332 | </dl> |
| 333 | </blockquote> |
| 334 | <p> |
| 335 | <a name="fn-deferred.prototype.adderrback"></a> |
| 336 | <a class="mochidef reference" href="#fn-deferred.prototype.adderrback">Deferred.prototype.addErrback(func)</a>:</p> |
| 337 | <blockquote> |
| 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> |
| 350 | </dl> |
| 351 | </blockquote> |
| 352 | <p> |
| 353 | <a name="fn-deferred.prototype.callback"></a> |
| 354 | <a class="mochidef reference" href="#fn-deferred.prototype.callback">Deferred.prototype.callback([result])</a>:</p> |
| 355 | <blockquote> |
| 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> |
| 363 | </dl> |
| 364 | </blockquote> |
| 365 | <p> |
| 366 | <a name="fn-deferred.prototype.cancel"></a> |
| 367 | <a class="mochidef reference" href="#fn-deferred.prototype.cancel">Deferred.prototype.cancel()</a>:</p> |
| 368 | <blockquote> |
| 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> |
| 377 | </dl> |
| 378 | </blockquote> |
| 379 | <p> |
| 380 | <a name="fn-deferred.prototype.errback"></a> |
| 381 | <a class="mochidef reference" href="#fn-deferred.prototype.errback">Deferred.prototype.errback([result])</a>:</p> |
| 382 | <blockquote> |
| 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 |
| 388 | on a |
| 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> |
| 394 | </dl> |
| 395 | </blockquote> |
| 396 | <p> |
| 397 | <a name="fn-deferredlock"></a> |
| 398 | <a class="mochidef reference" href="#fn-deferredlock">DeferredLock()</a>:</p> |
| 399 | <blockquote> |
| 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 |
| 403 | property.</p> |
| 404 | <dl class="docutils"> |
| 405 | <dt><em>Availability</em>:</dt> |
| 406 | <dd>Available in MochiKit 1.3.1+</dd> |
| 407 | </dl> |
| 408 | </blockquote> |
| 409 | <p> |
| 410 | <a name="fn-deferredlock.prototype.acquire"></a> |
| 411 | <a class="mochidef reference" href="#fn-deferredlock.prototype.acquire">DeferredLock.prototype.acquire()</a>:</p> |
| 412 | <blockquote> |
| 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> |
| 420 | </dl> |
| 421 | </blockquote> |
| 422 | <p> |
| 423 | <a name="fn-deferredlock.prototype.release"></a> |
| 424 | <a class="mochidef reference" href="#fn-deferredlock.prototype.release">DeferredLock.prototype.release()</a>:</p> |
| 425 | <blockquote> |
| 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> |
| 431 | </dl> |
| 432 | </blockquote> |
| 433 | <p> |
| 434 | <a name="fn-deferredlist"></a> |
| 435 | <a class="mochidef reference" href="#fn-deferredlist">DeferredList(list, [fireOnOneCallback, fireOnOneErrback, consumeErrors, canceller])</a>:</p> |
| 436 | <blockquote> |
| 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 |
| 440 | error.</p> |
| 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> |
| 453 | </dl> |
| 454 | <p>Example:</p> |
| 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) { |
| 462 | if (result[0]) { |
| 463 | alert("Data is here: " + result[1]); |
| 464 | } else { |
| 465 | alert("Got an error: " + result[1]); |
| 466 | } |
| 467 | }, resultList); |
| 468 | }); |
| 469 | </pre> |
| 470 | <dl class="docutils"> |
| 471 | <dt><em>Availability</em>:</dt> |
| 472 | <dd>Available in MochiKit 1.3.1+</dd> |
| 473 | </dl> |
| 474 | </blockquote> |
| 475 | </div> |
| 476 | <div class="section"> |
| 477 | <h2><a id="functions" name="functions">Functions</a></h2> |
| 478 | <p> |
| 479 | <a name="fn-calllater"></a> |
| 480 | <a class="mochidef reference" href="#fn-calllater">callLater(seconds, func[, args...])</a>:</p> |
| 481 | <blockquote> |
| 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() }); |
| 487 | </pre> |
| 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> |
| 492 | </dl> |
| 493 | </blockquote> |
| 494 | <p> |
| 495 | <a name="fn-doxhr"></a> |
| 496 | <a class="mochidef reference" href="#fn-doxhr">doXHR(url[, {option: value, ...}])</a>:</p> |
| 497 | <blockquote> |
| 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> |
| 507 | </dl> |
| 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> |
| 535 | </dl> |
| 536 | </blockquote> |
| 537 | <p> |
| 538 | <a name="fn-dosimplexmlhttprequest"></a> |
| 539 | <a class="mochidef reference" href="#fn-dosimplexmlhttprequest">doSimpleXMLHttpRequest(url[, queryArguments...])</a>:</p> |
| 540 | <blockquote> |
| 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"}); |
| 559 | </pre> |
| 560 | </dd> |
| 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 |
| 566 | MochiKit 1.4.</dd> |
| 567 | </dl> |
| 568 | </blockquote> |
| 569 | <p> |
| 570 | <a name="fn-evaljsonrequest"></a> |
| 571 | <a class="mochidef reference" href="#fn-evaljsonrequest">evalJSONRequest(req)</a>:</p> |
| 572 | <blockquote> |
| 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 |
| 577 | evaluated</dd> |
| 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> |
| 582 | </dl> |
| 583 | </blockquote> |
| 584 | <p> |
| 585 | <a name="fn-fail"></a> |
| 586 | <a class="mochidef reference" href="#fn-fail">fail([result])</a>:</p> |
| 587 | <blockquote> |
| 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> |
| 599 | </dl> |
| 600 | </blockquote> |
| 601 | <p> |
| 602 | <a name="fn-gatherresults"></a> |
| 603 | <a class="mochidef reference" href="#fn-gatherresults">gatherResults(deferreds)</a>:</p> |
| 604 | <blockquote> |
| 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> |
| 612 | </dl> |
| 613 | </blockquote> |
| 614 | <p> |
| 615 | <a name="fn-getxmlhttprequest"></a> |
| 616 | <a class="mochidef reference" href="#fn-getxmlhttprequest">getXMLHttpRequest()</a>:</p> |
| 617 | <blockquote> |
| 618 | <p>Return an <tt class="docutils literal"><span class="pre">XMLHttpRequest</span></tt> compliant object for the current |
| 619 | platform.</p> |
| 620 | <p>In order of preference:</p> |
| 621 | <ul class="simple"> |
| 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> |
| 626 | </ul> |
| 627 | <dl class="docutils"> |
| 628 | <dt><em>Availability</em>:</dt> |
| 629 | <dd>Available in MochiKit 1.3.1+</dd> |
| 630 | </dl> |
| 631 | </blockquote> |
| 632 | <p> |
| 633 | <a name="fn-maybedeferred"></a> |
| 634 | <a class="mochidef reference" href="#fn-maybedeferred">maybeDeferred(func[, argument...])</a>:</p> |
| 635 | <blockquote> |
| 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> |
| 647 | </dl> |
| 648 | </blockquote> |
| 649 | <p> |
| 650 | <a name="fn-loadjsondoc"></a> |
| 651 | <a class="mochidef reference" href="#fn-loadjsondoc">loadJSONDoc(url[, queryArguments...])</a>:</p> |
| 652 | <blockquote> |
| 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"}); |
| 667 | </pre> |
| 668 | </dd> |
| 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> |
| 674 | </dl> |
| 675 | </blockquote> |
| 676 | <p> |
| 677 | <a name="fn-sendxmlhttprequest"></a> |
| 678 | <a class="mochidef reference" href="#fn-sendxmlhttprequest">sendXMLHttpRequest(req[, sendContent])</a>:</p> |
| 679 | <blockquote> |
| 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 |
| 690 | called).</dd> |
| 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 |
| 699 | MochiKit 1.4.</dd> |
| 700 | </dl> |
| 701 | </blockquote> |
| 702 | <p> |
| 703 | <a name="fn-succeed"></a> |
| 704 | <a class="mochidef reference" href="#fn-succeed">succeed([result])</a>:</p> |
| 705 | <blockquote> |
| 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> |
| 722 | </dl> |
| 723 | </blockquote> |
| 724 | <p> |
| 725 | <a name="fn-wait"></a> |
| 726 | <a class="mochidef reference" href="#fn-wait">wait(seconds[, res])</a>:</p> |
| 727 | <blockquote> |
| 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 |
| 730 | elapsed.</p> |
| 731 | <dl class="docutils"> |
| 732 | <dt><em>Availability</em>:</dt> |
| 733 | <dd>Available in MochiKit 1.3.1+</dd> |
| 734 | </dl> |
| 735 | </blockquote> |
| 736 | </div> |
| 737 | </div> |
| 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> |
| 742 | <tbody valign="top"> |
| 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> |
| 744 | </tbody> |
| 745 | </table> |
| 746 | <table class="docutils footnote" frame="void" id="id8" rules="none"> |
| 747 | <colgroup><col class="label" /><col /></colgroup> |
| 748 | <tbody valign="top"> |
| 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> |
| 750 | </tbody> |
| 751 | </table> |
| 752 | <table class="docutils footnote" frame="void" id="id9" rules="none"> |
| 753 | <colgroup><col class="label" /><col /></colgroup> |
| 754 | <tbody valign="top"> |
| 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> |
| 756 | </tbody> |
| 757 | </table> |
| 758 | <table class="docutils footnote" frame="void" id="id10" rules="none"> |
| 759 | <colgroup><col class="label" /><col /></colgroup> |
| 760 | <tbody valign="top"> |
| 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> |
| 762 | </tbody> |
| 763 | </table> |
| 764 | </div> |
| 765 | <div class="section"> |
| 766 | <h1><a id="authors" name="authors">Authors</a></h1> |
| 767 | <ul class="simple"> |
| 768 | <li>Bob Ippolito <<a class="reference" href="mailto:bob@redivi.com">bob@redivi.com</a>></li> |
| 769 | </ul> |
| 770 | </div> |
| 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 |
| 776 | v2.1</a>.</p> |
| 777 | </div> |
| 778 | </div> |
| 779 | |
| 780 | </body> |
| 781 | </html> |