Opened 17 years ago

Closed 16 years ago

Last modified 5 years ago

#1022 defect closed fixed (fixed)

Explain Deferred for users familiar with callbacks

Reported by: hypatia Owned by: edsuom
Priority: high Milestone:
Component: core Keywords: documentation
Cc: Predictive Branch:


Attachments (1)

async.EAS.xhtml (16.0 KB) - added by edsuom 16 years ago.
Updated version of "Asynchronous Programming with Twisted"

Download all attachments as: .zip

Change History (7)

comment:1 Changed 17 years ago by 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.

comment:2 Changed 16 years ago by hypatia

Cc: hypatia removed
Component: conch
Owner: changed from hypatia to edsuom

Changed 16 years ago by edsuom

Attachment: async.EAS.xhtml added

Updated version of "Asynchronous Programming with Twisted"

comment:3 Changed 16 years ago by edsuom

Resolution: fixed
Status: newclosed

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!

comment:4 Changed 16 years ago by edsuom

Component: conchcore

comment:5 Changed 16 years ago by edsuom

Keywords: review added

comment:6 Changed 5 years ago by hawkowl

Keywords: review removed

[mass edit] Removing review from closed tickets.

Note: See TracTickets for help on using tickets.