[Twisted-Python] Updated defer.html

Clark C. Evans cce at clarkevans.com
Mon Mar 10 11:17:07 EST 2003


On Mon, Mar 10, 2003 at 07:55:50PM +1100, Andrew Bennetts wrote:
| I was going to reply to Clark directly, but others have already made much
| the same points... :)

Oh, I'm not one to take critique too personally... if I don't
"get it", I don't get it.  ;)

| > On Sun, Mar 09, 2003 at 09:39:19PM +0000, Clark C. Evans wrote:
| > > Documenting Deferreds suffers from a bootstrap problem; it is 
| > > advantageous to introduce Deferreds before Threads, but to 
| > > understand why you need Deferrerds you must already have
| > > read about Threads.   The typical solution to a bootstrap 
| > 
| > This makes no sense. Almost *all* of Deferreds used in Twisted (and
| > certainly most Twisted-using code) have nothing to do with threads.
| 
| Indeed!  There is virtually no need to mention threads in defer.html at all.

Ok. I'll re-write to pull threads out.  I was just trying
to re-write the code so that it was runnable.  In particular,
I was looking for a trivial example of something which would
be defered.   Perhaps a small example using reactor.callLater
would be a better choice.

| > Anyway, I think having one (runnable) example that doesn't even depend
| > on asynchrony might even be a good thing. Something like:
| > 
| >   d = Deferred()
| >   d.addCallbacks(...)
| >   d.callback(x)
| >   # maybe another d.addCallbacks(), etc
| 
| Yes, that's a good idea.  It's worth emphasising that there's really no
| voodoo here.  Possibly even demonstrate it in an interactive session, so
| that it is really clear that nothing happens until it is called.

Yes, good idea.

| > The point would be to show that indeed Deferreds don't have anything
| > special to do with asynchrony (or especially threads), as well make it
| > more clear what Deferreds are really doing, by showing it in the
| > simplest manner possible.
| 
| Which reminds me: the title should probably be "Deferred Results".  I think
| perhaps this is what confuses people; Deferreds aren't about delaying
| execution arbitrarily, or doing work in threads, or hooking into the event
| loop, they're about handling results that haven't arrived yet.  A Deferred
| doesn't represent a *callback*, it represents a *result*, and it provides
| simple (and powerful) ways to register callbacks to operate on the result,
| whenever it becomes available.

Great explanation.

| > So yeah, I think we should have a few good runnable examples in the
| > document, including one like I mentioned, as well as some "case-study"
| > things like threading, refID-mapping (This was mentioned in another
| > recent thread), etc.
| 
| Case studies would be worthwhile.  I don't really like the idea of padding
| out the document many more with more examples, because it's already a long
| read.  But adding a section to the end called Case Studies would allow
| plenty of room to add complete, verbose examples, without detracting from
| the exposition of the core concepts.
| 
| So in my opinion, the code samples should be left pretty much as they were
| -- minimal, clear examples of the general principles, not necessarily
| ready-to-run, and then add case studies to the end.  I'm even tempted to say
| this is a pattern that more of the docs should follow.... :)

I think the CaseStudies should kinda be distinct, in the
"Examples" directory or something like that.   However,
the 'deferred' could give an index of how the concept
was used in various examples.

I don't have time to further patch today/tomorow, but I'll
fix it by Wed.

Clark




More information about the Twisted-Python mailing list