Better documentation for STG UpdateFlag
Summary
In !11045 (comment 518768), we established that there is not a lot of documentation about updatable vs re-entrant closures. There is currently documentation at https://gitlab.haskell.org/ghc/ghc/-/blob/bf885d7a1a27e7b1cc34335a1e16d699fe084b47/compiler/GHC/Stg/Syntax.hs#L688-702, but it is a bit terse.
Proposed improvements or changes
I suggest adding a bit more text explaining why and when one should be used over the other, such as I do here: !11045 (comment 518772).
Simon suggests several more changes (!11045 (comment 520256)):
I would
- lay this comment out with bullets
- point to the relevant section of the STG paper
- make it into a Note
- say that in fact, although SingleEntry can be black-holed, Andreas says that we don't.
- so in fact SingleEntry and ReEntrant are treated identically -- I think! (Worth checking.)
One other difference is that I think that, as a debug mechanism, you can ask for SingleEntry thunks to be eagerly-blackholed with a special entry point so that if they are ever entered again (which should never happen) you get a nice error "Entered a single entry thunk twice". I don't know where that is done, but I'm sure it can be done, and was in the past... just not sure if that facility is in the current code base