Part of twisted.internet View Source
Support for results that aren't immediately available.Maintainer: Glyph Lefkowitz
|Function||succeed||Return a Deferred that has already had '.callback(result)' called.|
|Function||fail||Return a Deferred that has already had '.errback(result)' called.|
|Function||execute||Create a deferred from a callable and arguments.|
|Function||maybeDeferred||Invoke a function that may or may not return a deferred.|
|Function||setDebugging||Enable or disable Deferred debugging.|
|Function||getDebugging||Determine whether Deferred debugging is enabled.|
|Class||Deferred||This is a callback which will be put off until later.|
|Class||DebugInfo||Deferred debug helper|
|Class||FirstError||First error to occur in a
|Class||DeferredList||I combine a group of deferreds into one callback.|
|Function||gatherResults||Returns list with result of given Deferreds.|
|Function||returnValue||Return val from a
|Function||inlineCallbacks||WARNING: this function will not work in Python 2.4 and earlier!|
|Class||DeferredLock||A lock for event driven systems.|
|Class||DeferredSemaphore||A semaphore for event driven systems.|
|Class||DeferredQueue||An event driven queue.|
|Class||AlreadyTryingToLockError||Raised when DeferredFilesystemLock.deferUntilLocked is called twice on a single DeferredFilesystemLock.|
|Class||DeferredFilesystemLock||A FilesystemLock that allows for a deferred to be fired when the lock is acquired.|
|Class||_ConcurrencyPrimitive||No class docstring; 1/3 methods documented|
Return a Deferred that has already had '.callback(result)' called.
This is useful when you're writing synchronous code to an asynchronous interface: i.e., some code is calling you expecting a Deferred result, but you don't actually need to do anything asynchronous. Just return defer.succeed(theResult).See
failfor a version of this function that uses a failing Deferred rather than a successful one.
|Parameters||result||The result to give to the Deferred's 'callback' method.|
|Returns|| (type: |
Return a Deferred that has already had '.errback(result)' called.See
succeed's docstring for rationale.
|Parameters||result||The same argument that |
|Returns|| (type: |
Create a deferred from a callable and arguments.Call the given function with the given arguments. Return a deferred which has been fired with its callback as the result of that invocation or its errback with a Failure for the exception thrown.
Invoke a function that may or may not return a deferred.Call the given function with the given arguments. If the returned object is a
Deferred, return it. If the returned object is a
Failure, wrap it with
failand return it. Otherwise, wrap it in
succeedand return it. If an exception is raised, convert it to a
Failure, wrap it in
fail, and then return it.
|Parameters||f||The callable to invoke (type: Any callable )|
|args||The arguments to pass to |
|kw||The keyword arguments to pass to |
|Returns||The result of the function call, wrapped in a |
Enable or disable Deferred debugging.When debugging is on, the call stacks from creation and invocation are recorded, and added to any AlreadyCalledErrors we raise.
Returns list with result of given Deferreds.This builds on
DeferredListbut is useful since you don't need to parse the result for success/failure.
|Parameters||deferredList|| (type: |
deferredGenerator and waitForDeferred help you write Deferred-using code
that looks like a regular sequential function. If your code has a minimum
requirement of Python 2.5, consider the use of
instead, which can accomplish the same thing in a more concise manner.
def thingummy(): thing = waitForDeferred(makeSomeRequestResultingInDeferred()) yield thing thing = thing.getResult() print thing #the result! hoorj! thingummy = deferredGenerator(thingummy)
waitForDeferred returns something that you should immediately yield;
when your generator is resumed, calling thing.getResult() will either give
you the result of the Deferred if it was a success, or raise an exception
if it was a failure. Calling
getResult is absolutely
mandatory. If you do not call it, your program will not
deferredGenerator takes one of these waitForDeferred-using generator
functions and converts it into a function that returns a Deferred. The
result of the Deferred will be the last value that your generator yielded
unless the last value is a waitForDeferred instance, in which case the
result will be
None. If the function raises an unhandled
exception, the Deferred will errback instead. Remember that 'return
result' won't work; use 'yield result; return' in place of that.
Note that not yielding anything from your generator will make the Deferred result in None. Yielding a Deferred from your generator is also an error condition; always yield waitForDeferred(d) instead.The Deferred returned from your deferred generator may also errback if your generator raised an exception. For example:
def thingummy(): thing = waitForDeferred(makeSomeRequestResultingInDeferred()) yield thing thing = thing.getResult() if thing == 'I love Twisted': # will become the result of the Deferred yield 'TWISTED IS GREAT!' return else: # will trigger an errback raise Exception('DESTROY ALL LIFE') thingummy = deferredGenerator(thingummy)Put succinctly, these functions connect deferred-using code with this 'fake blocking' style in both directions: waitForDeferred converts from a Deferred to the 'blocking' style, and deferredGenerator converts from the 'blocking' style to a Deferred.
Return val from a
Note: this is currently implemented by raising an exception derived from BaseException. You might want to change any 'except:' clauses to an 'except Exception:' clause so as not to catch this exception.Also: while this function currently will work when called from within arbitrary functions called from within the generator, do not rely upon this behavior.
WARNING: this function will not work in Python 2.4 and earlier!inlineCallbacks helps you write Deferred-using code that looks like a regular sequential function. This function uses features of Python 2.5 generators. If you need to be compatible with Python 2.4 or before, use the
deferredGeneratorfunction instead, which accomplishes the same thing, but with somewhat more boilerplate. For example:
def thingummy(): thing = yield makeSomeRequestResultingInDeferred() print thing #the result! hoorj! thingummy = inlineCallbacks(thingummy)
When you call anything that results in a Deferred, you can simply yield it; your generator will automatically be resumed when the Deferred's result is available. The generator will be sent the result of the Deferred with the 'send' method on generators, or if the result was a failure, 'throw'.
Your inlineCallbacks-enabled generator will return a Deferred object, which will result in the return value of the generator (or will fail with a failure object if your generator raises an unhandled exception). Note that you can't use 'return result' to return a value; use 'returnValue(result)' instead. Falling off the end of the generator, or simply using 'return' will cause the Deferred to have a result of None.The Deferred returned from your deferred generator may errback if your generator raised an exception:
def thingummy(): thing = yield makeSomeRequestResultingInDeferred() if thing == 'I love Twisted': # will become the result of the Deferred returnValue('TWISTED IS GREAT!') else: # will trigger an errback raise Exception('DESTROY ALL LIFE') thingummy = inlineCallbacks(thingummy)