[Twisted-Python] Deferred documentation.

[Werner Thie]

On 3/22/11 2:30 AM, Jasper St. Pierre wrote:
> On IRC, exarkun, glyph, spiv and idnar encouraged me to do a bit of
> work on the Defer documentation. I kept get confused between the
> things like returning a Deferred from a callback and chainDeferred,
> which I found out wasn't that useful:
>
> <idnar>  I suppose it's useful for "forking" a deferred
> <idnar>  you have an "existing" deferred
> <idnar>  and you want a "new" deferred that starts with the value from
> the end of the existing deferred's callback chain
> <idnar>  but you don't want the rest of the existing deferred's
> callback chain to be affected by the new deferred's callback chain
> <idnar>  that's still not really a use case though, just a description
> of the situation that must arise in the use case
> <idnar>  I guess I should search for actual uses of chainDeferred
>
> Well, I was getting frustrated myself, and I suggested to fix the docs
> once and for all. People pointed me to three documents, all of which
> felt way too dense for me:
>
> http://twistedmatrix.com/documents/current/core/howto/defer.html
> http://twistedmatrix.com/documents/current/core/howto/gendefer.html
> http://twistedmatrix.com/documents/current/core/howto/deferredindepth.html
>
> Jessica also pointed me to http://twistedmatrix.com/trac/ticket/3943,
> which admittedly I haven't read yet.
>
> So, I started writing. I opened up a session of emacs, and produced two things:
>
> http://magcius.mecheye.net/twisted/DeferHowTo-Rewrite.html
> http://magcius.mecheye.net/twisted/DeferHowTo-Fixup.html
>
> Sources:
>
> http://magcius.mecheye.net/twisted/DeferHowTo-Rewrite.rst
> http://magcius.mecheye.net/twisted/DeferHowTo-Fixup.lore
>
> The former is a tutorial that I tried to make informal as possible,
> and the latter is a fixup and rewrite of defer.xhtml stuff to make it
> a bit less, uh, dense.
>
> My eventual goal is to reduce the number of documentation about defer
> down to a near-impossible two documents. I'm hoping to merge some of
> the good stuff of the other thousands of documents.
>
> Thoughts so far?
>
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python

Thank you for tackling the impossible.

I remember when reading the old docs the first time that one thing 
bothered me most and this was 'if I get a deferred back, then I'm kind 
of responsible for that beast' so what do I do with it besides adding 
call/errbacks'? I had a hard time and quite a few hours with the 
debugger to figure out the life cycle of a deferred. I also read 
gendefer.html over and over again while trying to figure out the 
relation of a deferred to the reactor, because somehow it must be that 
reactor.run() loop which in the end triggers either call- or errbacks.

This might be typical questions from someone who grew up without garbage 
collection. My problem is, that for coding in a confident way I have to 
have a grasp of the innards of the system.

Summed up
- How does the life cycle of a deferred look like?
- Who is responsible for a deferred?
- If deferreds are related to the reactor, then how are they related?

Reading your two docs answers those questions I had back then, 
definitely an improvement.

Minor glitches:

link to node.js is >> http://nodejs.org/

Thanks again, Werner