I am writing a chapter for a book called "Beautiful code", edited by Greg Wilson. The chapter is a tutorial about Software Transactional Memory in Haskell.
I would welcome any comments or questions you have on the paper, or constructive suggestions for improving it; the more concrete the better. You can see what people said about version 1 on the version 1 talk page: Talk:SantaClausProblem .
The book is aimed at a general audience of programmers, not Haskell geeks, so I have tried to explain everything necessary as I go along. So if you are not a Haskell expert, your input would be particularly valuable to me.
You can email me directly (firstname.lastname@example.org), or add Wiki talk notes below.
If you give your real name somewhere in your text (or email it to me), I'll add you to the acknowledgements at the end of the chapter. Notably, I'd like to acknowledge Steven807, Tibbe, Fanf, Garious, Rycee, Brecknell, Mvanier, Gaal, Fernando, Gknauth, EngineerScotty, BoAdler.
Simonpj 14:26, 22 December 2006 (UTC) To add a note, begin with four tilde signs ~~~~; the Wiki will fill in your user name and date.
Brecknell 13:38, 11 January 2007 (UTC) In Figure 1, retry should be STM a, not STM ().
Sylvain 13:45, 11 January 2007 (UTC) small points: since you go through explaining that the do-notation is overloaded and works for STM as well as IO (page 8), you might want to tell the same for return on page 11 (return being given with a type a -> IO a on page 5). There is also a double "Here is the code" at the bottom of page 17.
Brecknell 13:59, 11 January 2007 (UTC) The rewrite of the paragraph at top of page 17 has left behind a fragment that I think just needs to be deleted: "just runs each of the actions in sequence".
Brecknell 14:15, 11 January 2007 (UTC) Last sentence of page 18: "Here is another way approach that..." Delete either "way" or "approach".
ArthurVanLeeuwen 14:27, 11 January 2007 (UTC) minor stuff, really:
- page 2, middle of page: syncrhonized -> synchronized
- page 5, top of page: For example, here are two Haskell functions -> For example, here are the type signatures for two Haskell functions (the functions themselves may be primitives, after all)
- page 5, second paragraph: do the parentheses around hPutStr serve more than to confuse? Especially given their absence for hEchoLine...
- page 5, footnote 3: comma after effects
- page 6: make discarding the return value of forkIO in the second example main more explicit, e.g. with a footnote
- page 7, after Atomicity: This ensured -> This ensures
Brecknell 14:32, 11 January 2007 (UTC) I like the way you build up to the definition of "choose" in this new revision. I think this helps to convey how STM and actions as first-class values can improve modularity and composability in concurrent applications. So, if you like, you can consider my lsat comment on the previous revision "done", as well.
Maeder 14:38, 11 January 2007 (UTC)
- page 11, use subtract (+ -> -) in limitedWithDraw
- page 22 (2nd line), the the -> the
Genneth 15:07, 11 January 2007 (UTC) p4: make analogy between () and void to help non-haskellers
ArthurVanLeeuwen 15:10, 11 January 2007 (UTC) The bottom of page 17 has 'Here is his code:' in duplicate.
ArthurVanLeeuwen 15:19, 11 January 2007 (UTC) The note 'The code for choose is brief, but a little mind-bending:' on page 19 is very short, for such a leap in required understanding. In just one single block of 7 lines you introduce both the concept of IO actions encapsulated inside STM actions as well as the concept of list comprehension. For a non-haskeller this is quite a lot.
Maeder 15:25, 11 January 2007 (UTC) maybe generalize nTimes on page 7 to type: Int -> (Int -> IO ()) -> IO () and use nTimes on page 16 instead of sequence_ and list comprehensions. (The function choose on page 19 is also higher order.)
Malcolm 15:27, 11 January 2007 (UTC)
- Intro, para 2, "Sadly, parallel program[s] are" - missing plural
- sec 2.1, para 3, "if two thread[s] call" - missing plural
- sec 3.2, Atomicity, "This ensured that" -> "This ensures that"
Maeder 15:35, 11 January 2007 (UTC) maybe use putStrLn (hPutStrLn) instead of \n in the strings
Malcolm 16:07, 11 January 2007 (UTC)
- page 11, limitedWithdraw2 in type signature, is called simply withdraw2 in definition
- sec 4.2 "remaining capactity" -> "remaining capacity" (x3)
- sec 4.3 "newGate makes [a] new Gate" - missing article
- top of page 17, orphan (non-)sentence ". just runs each of the actions in sequence."
- sec 4.4, "futher" -> "further"
- sec 4.4 "another way approach" -> "another approach"
- sec 6 "exectued" -> "executed"
- sec 6 "the the treatment" -> "the treatment"
Jmuk 04:14, 12 January 2007 (UTC) page 13, semicolons in helper1 are out of alignment
Fanf 19:34, 12 January 2007 (UTC) Minor nits:
- p.2: need semicolon at end of last java statement in each function.
- p.2: should you comment that the class has a withdraw method similar to the deposit method?
- p.4 paragraph about locks: you introduce the word "compositional" here - perhaps better to stick with "modular"?
- bottom of p. 4: should "can" be omitted, or should it read "we must explain"?
- bottom of p. 7: inconsistent tense: began -> begins.
- Should the layout of the do notation be more like normal C layout, to avoid freaking out the mundanes?
- would openGate be a clearer name for operateGate?
- footnote p. 14: mkGate -> MkGate
- santa's code: perhaps a comment between two gates to note that the elves or reindeers do their things at that point.
- limitedWithdraw: is the test (amount > 0) redundant?
Fanf 19:45, 12 January 2007 (UTC) Section 4 introduction: The description of the problem reads like a description of an implementation, and I think it should be more story-like. e.g.
Santa spends most of his time asleep. On Christmas Eve, his nine reindeer return from their holidays and wake up Santa. He harnesses each of them to his sleigh, delivers toys with them and finally unharnesses them, allowing them to return to their holidays. All year his ten elves are busy working to make toys, but every so often they will need to consult Santa about toy R&D in his study. Santa will only wake up and talk to three of them at a time, and of course their consultations are a lower priority than delivering toys.
- p.13 perhaps "sleep" should be "delay" for consistency with the terminology in the code, and to avoid confusion with what santa does - the elves are making toys during the delay, not sleeping.
- Also, is it worth noting that the reindeer gates model the harnessing and unharnessing?