- Link to document: http://twistedmatrix.com/projects/core/documentation/howto/threading.html
- Reviewer's name: Mary Gardiner
- Review date: 14 January 2006
- Years using some parts of Twisted: 3
- Overall level of comfort with Twisted: Reasonable amount
- Level of experience with the subject matter of this document: Reasonable amount
- Have read or used this document before: No
- Someone who has been exposed Twisted's core event model: that is, the reactor and Deferreds.
- Someone who is relatively new to Twisted, and whose understanding of the above may not be totally solid.
- When to use threads in Twisted: the kind of situations which require it, and the kind of situations in which it is a reasonable option.
- How to use threads in Twisted: the major API functions or whatever.
As you read the document, begin filling this out
Overall, I felt that this document's prerequisites matched my expectations reasonably well
Some specific examples where there seems to be some assumed knowledge include:
- threads are mentioned without any introduction or links
- thread safety is mentioned without any introduction or links
- Deferreds are mentioned without any introduction or links
Things I learned/I think someone would learn from this document are [be specific]:
- the major threading APIs in Twisted
Things that I think this document tries to teach people but that I couldn't understand by using it:
Nothing of note.
The following additions to and changes to the content would improve this document:
- some links to other Twisted event documents (eg the async stuff) would not go astray
- likewise, perhaps a link to a third-party document explaining exactly what threads are
- the whole question of when you might want to or need to use threads (mainly for third party APIs that block) is only very briefly touched on: this should be a whole section
- an explanation of, or link to an explanation of, what is meant by "thread safe"
- is there a reason that there's emphasis on the utility methods being in a different module?
- the APIs need to be linked to, not just mentioned
The following changes to the style of the document would make it easier to read:
- This sentence is rather convoluted: "For functions whose results we wish to get, we can have the result returned as a Deferred:". It might be better worded as something like: "If we want the result of the function run in a thread, the deferToThread method returns a deferred which will be fired with the result