Haskell Optimization handbook

[doyougnu]

rendered

Any and all comments or suggestions appreciated!

Ping @gbaz

[gbaz]

This looks really comprehensive! I'll try to make time to give it a more serious review.

On first glance, I would note that while teaching people about build tools and systems in general is definitely out of scope, a few example command lines would be very handy. Even as an old hand, who actually contributes to cabal even, I sometimes forget and have to look up exactly how to set the ticky profiling flags I want. I see people get hung up on this all the time. So a "cookbook" approach that does show common workflows to get profiling results with standard tools would be a useful complement to the more comprehensive guide on how to interpret and act on those results.

It also could be helpful to highlight auxiliary tools for analyzing and visualizing reports, such as those the ghc-prof library lists as clients (I have used a couple of these to useful effect): https://hackage.haskell.org/package/ghc-prof

[doyougnu]

a few example command lines would be very handy

Yes! This is a good idea and I've added it to the draft checklist for the tooling section. I could imagine a summary table of command line invocations for each tooling section (or where appropriate) such as:

## run a.out 5 times with perf tool and record basic statistics
perf -r5 ./a.out

## Sample CPU stack traces, once every 100 last level cache misses, for 5 seconds:
perf record -e LLC-load-misses -c 100 -ag -- sleep 5 

Bendan Gregg has a great table like this on his website. I think this format is great and in scope for this project and very useful.

[goldfirere]

This looks fantastic! I haven't thought about the actual workflow practices, etc., but this all seems very plausible.

One possible risk here is that the material ends up too advanced. This is in sympathy with @gbaz's post above, but even long-time Haskellers are sometimes missing basic knowledge. It might be helpful to have a plan to get feedback from the intended audience from time to time, explicitly asking about what easy(ish) material is missing.

🚀

[doyougnu]

It might be helpful to have a plan to get feedback from the intended audience from time to time, explicitly asking about what easy(ish) material is missing.

I agree, I think at the end of each phase is an ideal time for this. I've added these checks to the phase checklists in c49de51

One possible risk here is that the material ends up too advanced.

My preference (and hope) is that the handbook could offer a wide variety of techniques that are ordered according to how invasive the change is. That is, a partial ordering of optimizations where IntMap.Lazy --> IntMap.Strict < OneShot Monad trick. I think that as long there is a wide array of techniques this is doable.

My other thoughts is that maybe there is a missing section of Part 2 (maybe this should be 2.1) in the current ToC that is low hanging or easy things to try or perhaps Library aware changes. Tiny laziness optimizations like use strict folds, foldr for short circuiting foldl for TCO and move bang patterns inside tuples would fit in this section. Or to be more succinct, these items fit this hypothetical section because:

1. They are easy to understand
2. They do not require a lot of invasive changes, just add ' for a ! or swap a foldr for a foldl
3. The total time to perform the change is less than 5 minutes.

[doyougnu]

It also could be helpful to highlight auxiliary tools for analyzing and visualizing reports, such as those the ghc-prof library lists as clients (I have used a couple of these to useful effect): https://hackage.haskell.org/package/ghc-prof

Ah I had totally forgotten this existed. I've added these in the ToC under the building with -prof section

[Ericson2314]

This is bikeshedding, but I don't really like markdown, nor do I like how mdBook (the most popular option?) renders things.

My hunch would be for reStructuredText. It's decent, GHC and Cabla use it, and we just converted Alex and Happy docs to be like it too. Sphinx does a good job too, much better than mdBook.

If @doyougnu prefers markdown, fine. But if this choice was made somewhat arbitrarily, I would propose switching to reST.

[Ericson2314]

On to more serious matters, we do have and HFTT meeting coming up, and @gbaz has reminded us this on the docket.

While I am not one to be super excited about performance, @doyougnu has my trust based on his GHC work (including wresting with gnarly perf problems!), and the commitment from the HF is quite cheap. This to me wacks the scales well over to "yes", it's just great bang for buck!

[doyougnu]

This is bikeshedding, but I don't really like markdown, nor do I like how mdBook (the most popular option?) renders things.

My hunch would be for reStructuredText. It's decent, GHC and Cabla use it, and we just converted Alex and Happy docs to be like it too. Sphinx does a good job too, much better than mdBook.

If @doyougnu prefers markdown, fine. But if this choice was made somewhat arbitrarily, I would propose switching to reST.

I don't prefer markdown, I prefer org but I wouldn't force that on any would-be contributors. I think reStructuredText is a good idea and after reviewing its features I think i'll move this work over to it. I do think it is important that this proposal sticks to the idiomatic doc approach in the Haskell community, so that cabal and GHC use it means this should too in my book!

[gbaz]

With the understanding that the exact format of the book and also the toc are subject to change, the March 2 meeting of the tech committee approved this proposal. The HF can proceed with working with @doyougnu on steps towards publicizing and implementing this!

[gbaz]

@doyougnu btw how has this been going? Anything we can do to help.

[doyougnu]

@doyougnu btw how has this been going? Anything we can do to help.

It's going good! Although progress has slowed down in the last month because I'm on vacation (returning Monday) and I had to push to finish a deadline before said vacation so I didn't commit for about 10 days before vacation.

The working repository is here. I still have to get internal support to host it on a better domain name, finish out the table of contents, and protect the main branch.

So far the major blockers that have taken more time have been:

1. Using restructuredText. I had to learn it and figure out the working tech stack.
2. Then I had to packaged what I needed on nix in a nix flake so CI would build the book.
3. My last journal submission from my phd was finally accepted so it's stolen since writing time from this project.

But its pretty close to being done with phase 0. Probably another week or two. I wasn't going to accept contributions before phase 0 is done but if you want to help then these items are the best place to start:

1. Review the contribution documentation, or really any documentation in the repo. The process of assigning yourself to a chapter in github, and the expectations when opening a PR should be obvious to a reader and these documents haven't been tested or reviewed by any third party!
2. On the project dashboard you can take an item to review and review it. I'm sure some of my writing could use a lot of improvement!
3. Pick an easy ticket to begin, such as this one.

Also I'm open to any suggestions, and just FYI there is still some missing documentation such as the case study checklist.