Opened 8 years ago

Closed 4 years ago

#3943 enhancement closed duplicate (duplicate)

Rewrite deferred documentation

Reported by: ezyang Owned by: ezyang
Priority: normal Milestone:
Component: core Keywords:
Cc: ezyang Branch:
Author:

Description

There seems to be a general consensus (on #twisted at least), that the old documentation on Deferreds kind of sucks. The planned new outline is:

  • Synchronous to Asynchronous: The Method to the Madness
    • Convert synchronous code to asynchronous code
    • Why asynchronous?
  • Deferred
    • Basic operation
    • Convenience primitives (succeed, fail, execute, maybeDeferred)
    • Callback/Errback chaining
    • Timeouts
  • Composing deferreds
    • DeferredList/gatherResults
    • chainDeferred
  • Advanced topics
    • Deferred asynchronous primitives
    • Sugar syntax

One of the ideas behind the new documentation is that there is a mapping between synchronous code and asynchronous code, and as such copious examples to explain this are to be provided. In particular, errbacks are simply a userland reimplementation of exception handling.

I expect the hardest pieces to explain will be:

  1. The asynchronous paradigm shift
  2. Callback/Errback chaining (in which the method names are totally misleading; I'm going to take a "please ignore the abstraction barrier" approach to this one)
  3. Deferred composition

Attachments (2)

defer2.xhtml (5.6 KB) - added by ezyang 8 years ago.
Initial draft, contains the first section of four
defer2.2.xhtml (10.8 KB) - added by ezyang 8 years ago.
Revision two, part way through part 2

Download all attachments as: .zip

Change History (6)

comment:1 Changed 8 years ago by ezyang

Extra note: this rewrite does not address the issues of writing your own deferreds.

comment:2 Changed 8 years ago by rlotun

I also agree that the deferred documentation can do with some freshening up. I think there should be a section devoted to error handling - examples of how to use twisted.python.failure, and how they related to python exceptions. There should also be a section on batch processing with deferreds (this can be under 'Advanced' I suppose), covering the following topics:

  • task.Cooperator
  • defer.DeferredQueue
  • defer.DeferredSemaphore

I'd be happy to contribute code examples demonstrating all the above. Also, you may find these extremely useful blog posts I've bookmarked enlightening:

Changed 8 years ago by ezyang

Attachment: defer2.xhtml added

Initial draft, contains the first section of four

comment:3 Changed 8 years ago by ezyang

Cc: ezyang added
Status: newassigned

Changed 8 years ago by ezyang

Attachment: defer2.2.xhtml added

Revision two, part way through part 2

comment:4 Changed 4 years ago by Jonathan Lange

Resolution: duplicate
Status: assignedclosed

Since this ticket hasn't been updated for a while, and since #6180 has provided a new Deferred howto, I'm marking this as closed.

If the new documentation is not good enough, please file a ticket explaining why.

Note: See TracTickets for help on using tickets.