Please suggest anything you would like, I’m happy to make several rounds of improvement.
Lesson implementation decisions:
This lesson is focused on beginners.
The first draft of this lesson is 345 lines, which is on the shorter side compared to
other lessons.
The surface area of the Lazy module is small, so I took the opportunity to
supplement the lesson with a thorough explanation of evaluation strategies. This is
supplemental, however, and can be shortened or removed based on your preferences.
Without the supplemental section, the lesson is only 200 lines long.
Writing that call-by-value is the default evaluation strategy annoys me a bit; it is the evaluation strategy, full stop. And similarly when writing that one can “opt into” call-by-need and call-by-name. It might be better to say “emulate” or something akin to it.
I do not understand why you write that cached values can cause memory leaks. There is no difference between cached and uncached values; removing a lazy keyword should never be able to plug such a memory leak. You might, however, have a memory leak if a value has not yet been cached, especially if the inputs to its computation are larger than the result itself, e.g., lazy (List.length l). (Obviously, the same argument can be used the other way around, that is, call-by-value can cause a memory leak if the result is much larger than the inputs.) Also, call-by-name suffers from the same issue as call-by-need.
I am not sure it is worth separating call-by-value and eager evaluation. Indeed, toplevel definitions are just the arguments of the module constructor, so they are evaluated eagerly because of call-by-value. Similarly, I do not see the point of separating lazy and call-by-need. We end up reading the same things again and again.
There is no occurrence of the word “exception”, which is a bit surprising.
I appreciate the work that you’re doing here. A few suggestions:
Be consistent with terminology. You helpfully note the many synonyms across these various concepts but then use them interchangeably. I’d recommend picking one for each concept and then using it consistently.
I’d also suggest not using the term “lazy,” except when identifying it as a synonym and when referring to the Lazy module.
The current version assumes that the reader knows what a thunk is.
After the description of the two evaluation strategies, it would be helpful to construct a 2x3 table of expression evaluation by argument evaluation. This table could then be used to guide the rest of the tutorial.
Your table near the end about what strategies OCaml offers would fit nicely into such a 2x3 table.
I think that such a table could also help to address the repetitiveness that @silene mentions.
You might want to include something about pattern matching lazy values. This is sometimes a convenient way to force them—although pattern matching lazy in the function parameter can leads to something being more eager than it ought to be and can be a source of bugs, so it’s something to use with care.
Thank you for your comments. As a first pass on your feedback, I updated the lesson by:
removing the section on cached values and memory leaks
adding a list item and link to the real-world applications section that introduces Okasaki’s “Pure Functional Data Structures” as a means to make imperative data structures functional and efficient. I’ve also ordered the book to read about further. I appreciate the reference. A lot more could be said about this (such as referencing libraries like Batteries that use Lazy to implement imperative data structures in a functional framework), but don’t know if the limited format benefits from a lot more being said about it. Perhaps Okasaki’s data structures would make for a good advanced tutorial on the site to demonstrate how imperative data structures can be implemented in a functional style in the future?
Adding to the section on thunks and closures to demonstrate how they relate to Lazy, which adds more depth to the lesson while making it more accessible to beginner devs.
Moving the summary table above the discussion and examples of the evaluation strategies to provide a preview of the material presented.
To the larger topic about repetition, I take your points well. I took the approach of introducing the different types of evaluation strategies in isolation first, then applying them to OCaml’s context. It may be that rewriting the structure to introduce deferment strategies first, then using that context to more concisely apply it to the different evaluation strategies would lead to less repetition. I’ll weigh this option further, as it requires a larger rewrite.
I don’t think it really fits the format to describe in details Okasaki’s persistent data structures. My point was more than those data structures make the claim that laziness can be used for performance much more concrete.