| | 1 | = Review details = |
| | 2 | |
| | 3 | * Link to document: http://twistedmatrix.com/projects/core/documentation/howto/threading.html |
| | 4 | * Reviewer's name: Mary Gardiner |
| | 5 | * Review date: 14 January 2006 |
| | 6 | |
| | 7 | = User profile = |
| | 8 | |
| | 9 | * Years using some parts of Twisted: 3 |
| | 10 | * Overall level of comfort with Twisted: Reasonable amount |
| | 11 | * Level of experience with the subject matter of this document: Reasonable amount |
| | 12 | * Have read or used this document before: No |
| | 13 | |
| | 14 | = Document expectations = |
| | 15 | |
| | 16 | == Prerequisites == |
| | 17 | |
| | 18 | * Someone who has been exposed Twisted's core event model: that is, the reactor and Deferreds. |
| | 19 | * Someone who is relatively new to Twisted, and whose understanding of the above may not be totally solid. |
| | 20 | |
| | 21 | == Outcomes == |
| | 22 | |
| | 23 | * 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. |
| | 24 | * How to use threads in Twisted: the major API functions or whatever. |
| | 25 | |
| | 26 | = Document review = |
| | 27 | |
| | 28 | ''As you read the document, begin filling this out'' |
| | 29 | |
| | 30 | == Prerequisites == |
| | 31 | |
| | 32 | Overall, I felt that this document's prerequisites matched my expectations reasonably well |
| | 33 | |
| | 34 | Some specific examples where there seems to be some assumed knowledge include: |
| | 35 | |
| | 36 | * threads are mentioned without any introduction or links |
| | 37 | * thread safety is mentioned without any introduction or links |
| | 38 | * Deferreds are mentioned without any introduction or links |
| | 39 | |
| | 40 | == Outcomes == |
| | 41 | |
| | 42 | Things I learned/I think someone would learn from this document are ''[be specific]'': |
| | 43 | |
| | 44 | * the major threading APIs in Twisted |
| | 45 | |
| | 46 | Things that I think this document tries to teach people but that I couldn't understand by using it: |
| | 47 | |
| | 48 | Nothing of note. |
| | 49 | |
| | 50 | == Content suggestions == |
| | 51 | |
| | 52 | The following additions to and changes to the content would improve this document: |
| | 53 | |
| | 54 | * some links to other Twisted event documents (eg the async stuff) would not go astray |
| | 55 | * likewise, perhaps a link to a third-party document explaining exactly what threads are |
| | 56 | * 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 |
| | 57 | * an explanation of, or link to an explanation of, what is meant by "thread safe" |
| | 58 | * is there a reason that there's emphasis on the utility methods being in a different module? |
| | 59 | * the APIs need to be linked to, not just mentioned |
| | 60 | |
| | 61 | == Style == |
| | 62 | |
| | 63 | The following changes to the style of the document would make it easier to read: |
| | 64 | |
| | 65 | * 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 |
