diff --git a/doc/core/howto/defer.xhtml b/doc/core/howto/defer.xhtml index 21da54e..2a131d3 100644 --- a/doc/core/howto/defer.xhtml +++ b/doc/core/howto/defer.xhtml @@ -38,17 +38,19 @@ code.

Deferreds

Twisted uses the Deferred object to manage the callback -sequence. The client application attaches a series of functions to the -deferred to be called in order when the results of the asychronous request are -available (this series of functions is known as a series of -callbacks, or a callback chain), together -with a series of functions to be called if there is an error in the -asychronous request (known as a series of errbacks or an -errback chain). The asychronous library code calls the first -callback when the result is available, or the first errback when an error -occurs, and the Deferred object then hands the results of each -callback or errback function to the next function in the chain.

+base="twisted.internet.defer">Deferred object to manage the +callback sequence. The client application attaches a series of +functions to the deferred to be called in order when the results of +the asychronous request are available (this series of functions is +known as a series of callbacks, or a callback +chain), together with a series of functions to be called if +there is an error in the asychronous request (known as a series +of errbacks or an errback +chain). The asychronous library code calls the first callback +when the result is available, or the first errback when an error +occurs, and the Deferred object then hands the results of +each callback or errback function to the next function in the +chain.

Callbacks

@@ -296,18 +298,19 @@ d.addCallbacks(callback1, errback1) # C d.addCallbacks(callback2, errback2) -

If an error occurs in callback1, then for Case 1 -errback1 will be called with the failure. For Case -2, errback2 will be called. Be careful with your -callbacks and errbacks.

+

If an error occurs in callback1, then +for Case 1 errback1 will be called with +the failure. For Case 2, errback2 will be +called. Be careful with your callbacks and errbacks.

-

What this means in a practical sense is in Case 1, "A" will -handle a success condition from getDeferredFromSomewhere, and -"B" will handle any errors that occur from either the upstream -source, or that occur in 'A'. In Case 2, "C"'s errback1 -will only handle an error condition raised by -getDeferredFromSomewhere, it will not do any handling of -errors raised in callback1.

+

What this means in a practical sense is in Case 1, "A" +will handle a success condition +from getDeferredFromSomewhere, and "B" will +handle any errors that occur from either the upstream source, or +that occur in 'A'. In Case 2, "C"'s errback1 will +only handle an error condition raised +by getDeferredFromSomewhere, it will not do any +handling of errors raised in callback1.

Unhandled Errors

@@ -390,12 +393,15 @@ def asynchronousIsValidUser(d, user): return d -

Our original implementation of authenticateUser expected -isValidUser to be synchronous, but now we need to change it to handle both -synchronous and asynchronous implementations of isValidUser. For this, we -use maybeDeferred to -call isValidUser, ensuring that the result of isValidUser is a Deferred, -even if isValidUser is a synchronous function: +

Our original implementation of authenticateUser +expected isValidUser to be synchronous, but now we need +to change it to handle both synchronous and asynchronous +implementations of isValidUser. For this, we +use maybeDeferred to +call isValidUser, ensuring that the result +of isValidUser is a Deferred, even +if isValidUser is a synchronous function: 

@@ -413,8 +419,9 @@ def authenticateUser(isValidUser, user):

-Now isValidUser could be either synchronousIsValidUser or -asynchronousIsValidUser. +Now isValidUser could be +either synchronousIsValidUser +or asynchronousIsValidUser.

It is also possible to modify synchronousIsValidUser to return @@ -436,10 +443,11 @@ the Deferreds you want it to wait for:

dl = defer.DeferredList([deferred1, deferred2, deferred3]) -

You can now treat the DeferredList like an ordinary Deferred; you can call -addCallbacks and so on. The DeferredList will call its callback -when all the deferreds have completed. The callback will be called with a list -of the results of the Deferreds it contains, like so:

+

You can now treat the DeferredList like an ordinary Deferred; you +can call addCallbacks and so on. The DeferredList will +call its callback when all the deferreds have completed. The callback +will be called with a list of the results of the Deferreds it +contains, like so:

 def printResult(result):
@@ -518,31 +526,35 @@ deferred2.callback("two")
 
 
Other behaviours

 
-
DeferredList accepts three keyword arguments that modify its behaviour:
-fireOnOneCallback, fireOnOneErrback and
-consumeErrors.  If fireOnOneCallback is set, the
-DeferredList will immediately call its callback as soon as any of its Deferreds
-call their callback.  Similarly, fireOnOneErrback will call errback
-as soon as any of the Deferreds call their errback.  Note that DeferredList is
-still one-shot, like ordinary Deferreds, so after a callback or errback has been
-called the DeferredList will do nothing further (it will just silently ignore
-any other results from its Deferreds).

+
DeferredList accepts three keyword arguments that modify its
+behaviour: fireOnOneCallback, fireOnOneErrback
+and consumeErrors.  If fireOnOneCallback is
+set, the DeferredList will immediately call its callback as soon as
+any of its Deferreds call their callback.
+Similarly, fireOnOneErrback will call errback as soon as
+any of the Deferreds call their errback.  Note that DeferredList is
+still one-shot, like ordinary Deferreds, so after a callback or
+errback has been called the DeferredList will do nothing further (it
+will just silently ignore any other results from its Deferreds).

 
 
The fireOnOneErrback option is particularly useful when you
 want to wait for all the results if everything succeeds, but also want to know
 immediately if something fails.

 
-
The consumeErrors argument will stop the DeferredList from
-propagating any errors along the callback chains of any Deferreds it contains
-(usually creating a DeferredList has no effect on the results passed along the
-callbacks and errbacks of their Deferreds).  Stopping errors at the DeferredList
-with this option will prevent Unhandled error in Deferred warnings from
-the Deferreds it contains without needing to add extra errbacksUnless of course a later callback starts a fresh error —
-but as we've already noted, adding callbacks to a Deferred after its used in a
-DeferredList is confusing and usually avoided..  Passing a true value
-for the consumeErrors parameter will not change the behavior of
-fireOnOneCallback or fireOnOneErrback.

+
The consumeErrors argument will stop the DeferredList
+from propagating any errors along the callback chains of any Deferreds
+it contains (usually creating a DeferredList has no effect on the
+results passed along the callbacks and errbacks of their Deferreds).
+Stopping errors at the DeferredList with this option will
+prevent Unhandled error in Deferred warnings from the Deferreds
+it contains without needing to add extra
+errbacksUnless of course a later callback
+starts a fresh error — but as we've already noted, adding
+callbacks to a Deferred after its used in a DeferredList is confusing
+and usually avoided..  Passing a true value for
+the consumeErrors parameter will not change the behavior
+of fireOnOneCallback
+or fireOnOneErrback.

 
 
 
@@ -553,8 +565,9 @@ Deferred returned by a function. It is not meant to be a
 substitute for the docstrings in the Deferred class, but can provide guidelines
 for its use.

 
-
There is a parallel overview of functions used by the Deferred's
-creator in Generating Deferreds.

+
There is a parallel overview of functions used by the
+Deferred's creator
+in Generating Deferreds.

 
 
Basic Callback Functions

 
diff --git a/doc/core/howto/deferredindepth.xhtml b/doc/core/howto/deferredindepth.xhtml
index 9a7edfc..479a601 100644
--- a/doc/core/howto/deferredindepth.xhtml
+++ b/doc/core/howto/deferredindepth.xhtml
@@ -10,10 +10,10 @@
 
Introduction

 
 
Deferreds are quite possibly the single most confusing topic that a
-newcomer to Twisted has to deal with. I am going to forgo the normal talk
-about what deferreds are, what they aren't, and why they're used in Twisted.
-Instead, I'm going show you the logic behind what they
-do.

+newcomer to Twisted has to deal with. I am going to forgo the normal
+talk about what deferreds are, what they aren't, and why they're used
+in Twisted.  Instead, I'm going show you the logic behind what
+they do.

 
 
 
A deferred allows you to encapsulate the logic that you'd normally use to
@@ -254,11 +254,12 @@ callback 4
         got result: damage control successful!
-

Two things to note here. First, "- A -" was skipped, like we wanted it to, -and the second thing is that after "- A -", noDecision is called, because -it is the next errback that exists in the chain. It returns a -non-failure, so processing continues with the next callback at "- B -", and -the errback at the end of the chain is never called

+

Two things to note here. First, "- A -" was skipped, like +we wanted it to, and the second thing is that after "- A -", +noDecision is called, because it is the next errback that +exists in the chain. It returns a non-failure, so processing +continues with the next callback at "- B -", and the errback +at the end of the chain is never called

Hints, tips, common mistakes, and miscellaney

diff --git a/doc/core/howto/gendefer.xhtml b/doc/core/howto/gendefer.xhtml index d391ea0..47da1ba 100644 --- a/doc/core/howto/gendefer.xhtml +++ b/doc/core/howto/gendefer.xhtml @@ -120,8 +120,9 @@ print "Adding the callback now." d.addCallback(printNumber) -

You will notice that despite creating a Deferred in the -largeFibonnaciNumber function, these things happened:

+

You will notice that despite creating a Deferred in +the largeFibonnaciNumber function, these things +happened:

-

args and env have empty default values, but -many programs depend upon them to be set correctly. At the very least, -args[0] should probably be the same as executable. -If you just provide os.environ for env, the child -program will inherit the environment from the current process, which is -usually the civilized thing to do (unless you want to explicitly clean the -environment as a security precaution). The default is to give an empty -env to the child.

+

args and env have empty default values, +but many programs depend upon them to be set correctly. At the very +least, args[0] should probably be the same +as executable. If you just +provide os.environ for env, the child +program will inherit the environment from the current process, which +is usually the civilized thing to do (unless you want to explicitly +clean the environment as a security precaution). The default is to +give an empty env to the child.

reactor.spawnProcess returns an instance that implements @@ -167,8 +168,8 @@ reactor.run()

Things that can happen to your ProcessProtocol

-

These are the methods that you can usefully override in your subclass of -ProcessProtocol:

+

These are the methods that you can usefully override in your +subclass of ProcessProtocol: