Deferred documentation should give an example of how to integrate blocking code

[snacktime]

In the documentation on Deferred's in the howto section
(http://twistedmatrix.com/documents/current/howto/defer),  the examples
that show a blocking operation and then a non blocking operation do
not show what happened to the blocking code, it just conveniently
disappears.  For someone new to async programming it might help to
give an example that shows the blocking code being called via
deferToThread.  In other words show how you would handle blocking
code.  It doesn't matter if there are 10 ways of doing it, just one
example I think would go a long ways to illustrating the complete
idea.  I know when I was reading about Deferreds for the first time, I
was sitting there thinking 'Ok, I know the example doesn't block now
because they just conveniently yanked out the blocking code!!, but
what DID they do with it?'

[hypatia]

Re-titling bug to be more precise...
I'm in the middle of reworking the whole set of async/deferred docs so that it's
divided into three documents:
 1. An overview/introduction
 2. A discussion of the various ways to use Deferreds returned to you
 3. A discussion of the various ways of generating Deferreds in your own code
and returning them
Your suggestion is going to be part of doc #3 (or at least doc #3 will link to
the threading guide and probably give one example).
I'll update the bug as that proceeds.

[hypatia]

I've added an example of deferToThread to gendefer.xhtml in the documentation.
I'm not closing the bug, because deferToThread is really for third party
blocking code, not your own blocking code. I need to address defgen somewhere,
and link to the flow doc, and also explain how Twisted makes networking async
(or link to that) before closing the bug.

[hypatia]

Reassigning doc bugs to edsuom.

[edsuom]

There's undoubtedly work that can still be done on this bug, and I guess I'm the guy to do it. In the meantime, I wanted to note that I've done a lot of work trying to interface Twisted with blocking code. You may want to check out the enhancement of ticket:1768.