← Back to branch summary

~certify-web-dev/twisted/certify-trunk

« back to all changes in this revision

Viewing changes to doc/howto/defer.html

  • Committer: Bazaar Package Importer
  • Author(s): Free Ekanayaka
  • Date: 2010-03-09 13:32:00 UTC
  • mfrom: (2.2.6 sid)
  • Revision ID: james.westby@ubuntu.com-20100309133200-xs2rrzwnn9k86sbx
Tags: 10.0.0-2
* Include changes from 9.0.0-2 which got skipped
* python-twisted depends on version >= 10.0 of other packages

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/howto/defer.html
1
 
<?xml version="1.0" encoding="utf-8"?>
2
 
<!DOCTYPE html
3
 
  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'
4
 
  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>
5
 
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
 
1
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html  PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'  'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">
6
2
  <head>
7
3
<title>Twisted Documentation: Deferred Reference</title>
8
4
<link href="stylesheet.css" rel="stylesheet" type="text/css"/>
15
11
 
16
12
<span/>
17
13
 
18
 
<p>This document is a guide to the behaviour of the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> object, and to various
 
14
<p>This document is a guide to the behaviour of the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> object, and to various
19
15
ways you can use them when they are returned by functions.</p>
20
16
 
21
17
<p>This document assumes that you are familiar with the basic principle that
40
36
<a name="deferreds" shape="rect"/>
41
37
<h2>Deferreds<a name="auto0"/></h2>
42
38
 
43
 
<p>Twisted uses the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code> object to manage the callback
 
39
<p>Twisted uses the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">Deferred</a></code> object to manage the callback
44
40
sequence. The client application attaches a series of functions to the
45
41
deferred to be called in order when the results of the asychronous request are
46
42
available (this series of functions is known as a series of
54
50
 
55
51
<h2>Callbacks<a name="auto1"/></h2>
56
52
 
57
 
<p>A <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> is a promise that
 
53
<p>A <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.html" title="twisted.internet.defer.Deferred">twisted.internet.defer.Deferred</a></code> is a promise that
58
54
a function will at some point have a result.  We can attach callback functions
59
55
to a Deferred, and once it gets a result these callbacks will be called. In
60
56
addition Deferreds allow the developer to register a callback for an error,
283
279
  <li>When the result is ready, give it to the Deferred
284
280
  object. <code>.callback(result)</code> if the operation succeeded,
285
281
  <code>.errback(failure)</code> if it failed. Note that
286
 
  <code>failure</code> is typically an instance of a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>
 
282
  <code>failure</code> is typically an instance of a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>
287
283
  instance.</li>
288
284
  
289
285
  <li>Deferred object triggers previously-added (call/err)back
305
301
    statements.</li>
306
302
    
307
303
    <li>If an errback doesn't raise an exception or return a
308
 
    <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>
 
304
    <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code>
309
305
    instance, switch to callback.</li>
310
306
  </ul> </li>
311
307
</ol>
318
314
callbacks run, one after the other, as described above.</p>
319
315
 
320
316
<p>If the errback is called instead of the callback (e.g.  because a DB query
321
 
raised an error), then a <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> is passed into the first
 
317
raised an error), then a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> is passed into the first
322
318
errback (you can add multiple errbacks, just like with callbacks). You can
323
319
think of your errbacks as being like <code class="python">except</code> blocks
324
320
of ordinary Python code.</p>
337
333
so be careful. Make sure your errbacks return a <code class="python">Failure</code> (probably the one that was passed to it), or a
338
334
meaningful return value for the next callback.</p>
339
335
 
340
 
<p>Also, <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> instances have
 
336
<p>Also, <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.failure.Failure.html" title="twisted.python.failure.Failure">twisted.python.failure.Failure</a></code> instances have
341
337
a useful method called trap, allowing you to effectively do the equivalent
342
338
of:</p>
343
339
 
375
371
it re-raises the error.</p>
376
372
 
377
373
<p>There's another potential <q>gotcha</q> here.  There's a
378
 
method <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.Deferred.addCallbacks.html" title="twisted.internet.defer.Deferred.addCallbacks">twisted.internet.defer.Deferred.addCallbacks</a></code>
 
374
method <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.Deferred.addCallbacks.html" title="twisted.internet.defer.Deferred.addCallbacks">twisted.internet.defer.Deferred.addCallbacks</a></code>
379
375
which is similar to, but not exactly the same as, <code class="python">addCallback</code> followed by <code class="python">addErrback</code>. In particular, consider these two cases:</p>
380
376
 
381
377
<pre class="python"><p class="py-linenumber"> 1
519
515
<p> Our original implementation of <code>authenticateUser</code> expected
520
516
<code>isValidUser</code> to be synchronous, but now we need to change it to handle both
521
517
synchronous and asynchronous implementations of <code>isValidUser</code>. For this, we
522
 
use <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.maybeDeferred.html" title="twisted.internet.defer.maybeDeferred">maybeDeferred</a></code> to
 
518
use <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.maybeDeferred.html" title="twisted.internet.defer.maybeDeferred">maybeDeferred</a></code> to
523
519
call <code>isValidUser</code>, ensuring that the result of <code>isValidUser</code> is a Deferred,
524
520
even if <code>isValidUser</code> is a synchronous function:
525
521
</p>
561
557
 
562
558
<p>Sometimes you want to be notified after several different events have all
563
559
happened, rather than waiting for each one individually.  For example, you may
564
 
want to wait for all the connections in a list to close.  <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.internet.defer.DeferredList.html" title="twisted.internet.defer.DeferredList">twisted.internet.defer.DeferredList</a></code> is the way to do
 
560
want to wait for all the connections in a list to close.  <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.defer.DeferredList.html" title="twisted.internet.defer.DeferredList">twisted.internet.defer.DeferredList</a></code> is the way to do
565
561
this.</p>
566
562
 
567
563
<p>To create a DeferredList from multiple Deferreds, you simply pass a list of
839
835
DeferredList is confusing and usually avoided.</span></a></li></ol></div>
840
836
 
841
837
    <p><a href="index.html">Index</a></p>
842
 
    <span class="version">Version: 9.0.0</span>
 
838
    <span class="version">Version: 10.0.0</span>
843
839
  </body>
844
840
</html>
 
 
b'\\ No newline at end of file'