wiki:DocumentationAnalysis/Threads/MaryGardiner

Review details

User profile

  • 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

Document expectations

Prerequisites

  • 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.

Outcomes

  • 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.

Document review

As you read the document, begin filling this out

Prerequisites

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

Outcomes

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.

Content suggestions

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

Style

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
Last modified 8 years ago Last modified on 02/24/2006 09:58:47 PM