Part of twisted.internet View Source
Maintainer: Glyph Lefkowitz
Class | AlreadyCalledError | Undocumented |
Class | CancelledError | This error is raised by default when a Deferred is
cancelled. |
Class | TimeoutError | This exception is deprecated. It is used only by the deprecated
Deferred.setTimeout method. |
Function | logError | Undocumented |
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 | timeout | Undocumented |
Function | passthru | Undocumented |
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 DeferredList
if fireOnOneErrback is set. |
Class | DeferredList | DeferredList
is a tool for collecting the results of several Deferreds. |
Function | gatherResults | Returns, via a Deferred , a
list with the results of the given Deferred s - in
effect, a "join" of multiple deferred operations. |
Class | waitForDeferred | See deferredGenerator . |
Function | deferredGenerator | No summary |
Function | returnValue | Return val from a inlineCallbacks
generator. |
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 | QueueOverflow | Undocumented |
Class | QueueUnderflow | Undocumented |
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. |
Function | _parseDListResult | Undocumented |
Function | _deferGenerator | See deferredGenerator . |
Class | _DefGen_Return | Undocumented |
Function | _inlineCallbacks | See inlineCallbacks . |
Class | _ConcurrencyPrimitive | No class docstring; 1/3 methods documented |
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 fail
for
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: Deferred ) |
Deferred
that
has already had .errback(result)
called.
See succeed
's
docstring for rationale.
Parameters | result | The same argument that Deferred.errback
takes. |
Returns | (type: Deferred ) | |
Raises | NoCurrentExceptionError | If result is None but there is no current
exception state. |
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 fail
and return it. Otherwise, wrap it in succeed
and
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 f | |
kw | The keyword arguments to pass to f | |
Returns | The result of the function call, wrapped in a Deferred if
necessary. (type: Deferred ) |
Deferred
debugging.
When debugging is on, the call stacks from creation and invocation are
recorded, and added to any AlreadyCalledErrors
we raise.
Deferred
, a
list with the results of the given Deferred
s - in
effect, a "join" of multiple deferred operations.
The returned Deferred
will
fire when all of the provided Deferred
s have
fired, or when any one of them has failed.
This differs from DeferredList
in that you don't need to parse the result for success/failure.
Parameters | consumeErrors | (keyword param) a flag, defaulting to False, indicating that failures in
any of the given Deferreds should not be propagated to
errbacks added to the individual Deferreds after this gatherResults
invocation. Any such errors in the individual Deferred s will
be converted to a callback result of None . This is useful to
prevent spurious 'Unhandled error in Deferred' messages from being logged.
This parameter is available since 11.1.0. (type: bool ) |
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 inlineCallbacks
instead, which can accomplish the same thing in a more concise manner.
There are two important functions involved: waitForDeferred
,
and deferredGenerator
.
They are used together, like this:
@deferredGenerator def thingummy(): thing = waitForDeferred(makeSomeRequestResultingInDeferred()) yield thing thing = thing.getResult() print thing #the result! hoorj!
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 work.
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:
@deferredGenerator 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')
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
.
inlineCallbacks
generator.
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 deferredGenerator
function instead, which accomplishes the same thing, but with somewhat more
boilerplate. For example:
@inlineCallBacks def thingummy(): thing = yield makeSomeRequestResultingInDeferred() print thing #the result! hoorj!
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'.
Things that are not Deferred
s may
also be yielded, and your generator will be resumed with the same object
sent back. This means yield
performs an operation roughly
equivalent to maybeDeferred
.
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
.
Be aware that returnValue
will not accept a Deferred
as a
parameter. If you believe the thing you'd like to return could be a Deferred
, do
this:
result = yield result returnValue(result)
The Deferred
returned from your deferred generator may errback if your generator raised
an exception:
@inlineCallbacks 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')