Basically the way you use it is that you write your entire library in the way you would normally write it with Twisted: use Deferreds everywhere. There are two major differences, one at the outermost parts of your library and one at the innermost, and one rule on how they interact:
- In your blocking entrypoints, return the result of SynchronousDeferred.synchronize() instead of the deferred itself
- Anywhere you would do some long-running task, wrap SynchronousDeferreds around the blocking implementations but make the non-blocking implementations return regular Deferreds.
- When the user is using asynchronous entrypoints, try to use asynchronous low-level APIs. When the user is using synchronous entrypoints, definitely only use synchronous (SynchronousDeferred-returning) APIs.
synchronizereturns or raises the current value on a SynchronousDeferred immediately.
SynchronousDeferred doesn't have
errbackmethods like normal deferreds, as you have to pass the initial value of the Deferred straight to the constructor.
Project page: http://launchpad.net/synchronous-deferred
Code browse: http://codebrowse.launchpad.net/~radix/synchronous-deferred/trunk/files