[Twisted-Python] Updated defer.html

[Andrew Bennetts]

I was going to reply to Clark directly, but others have already made much
the same points... :)

On Sun, Mar 09, 2003 at 11:46:29PM -0500, Christopher Armstrong wrote:
> 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.

> 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.

> 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.

> 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.... :)

> <insert typical apologetic non-promise to implement here>

As always :)

-Andrew.