Explain Deferred for users familiar with callbacks

[hypatia]

Another suggestion arising from #1015.

"I'd have understood Deferreds a lot sooner if they had been presented as
callbacks on crack. Show the reader a simple callback design, then ask
'But what if you wanted to do x (set a different callback for error condition,
chain callbacks, etc)' and showing how deferreds solve that problem.
"Deferreds are beautiful!" kind of races through the how, and you're left 
wondering about the why."

I'm a bit wary about this one. A reasonable number of questions on IRC show that
people using Twisted may not know about callbacks (some of them don't know
anything about any concurrency mechanisms at all). In general, I'm a bit leery
of writing documentation that goes: "here's a way to do something! but wait!
that way is bad/deprecated! look, here's a better way!" I don't want to require
users who haven't already used other callback methods to have to learn them in
order to immediately discard them in favour of Deferreds.

The solution is probably to have two separate documents: Deferreds for people
new to async programming (including async evangelism as per #1020); and
Deferreds for people familiar with it. The latter would explain it in terms of
callbacks, the former would probably not demonstrate manually constructed
callback chains only to throw them away.

[edsuom]

Updated version of "Asynchronous Programming with Twisted"

[edsuom]

I've attached a revised version of "Asynchronous Programming with Twisted" that expands the discussion of how a Deferred acts as a manager for callbacks. It includes an analogy of how a Deferred is used that is hopefully instructive to novices and experienced callbackers alike:

You can picture a function that returns a Deferred as acting like a librarian who responds to a patron's question ("Are these mushrooms poisonous?") with a handwritten note saying, "I don't have your answer off the top of my head, but let me know where I can call you with the answer when I have it." The caller to the function does the equivalent of the patron scribbling a phone number on the note by attaching a callback to the Deferred. An equivalent of a deferred chain is where the patron writes several numbers on the note, and the person answering the phone at the first number responds to the answer ("They're highly poisonous") with another answer ("It's too late to use another recipe, our dinner party is canceled") that the librarian relays to whomever answers the phone (some disappointed dinner guest, perhaps) at the second number. Note that the library patron has been able to wander off and forget all about this matter in the meantime; such is the beauty of asynchronous programming!

[hawkowl]

[mass edit] Removing review from closed tickets.