Flaws in Infelicity Docs & Error Messages re Inliner Non-Termination
Summary
Location of documentation issue: GHC User's Guide §16.2.1: Bugs in GHC. More precisely, the item regarding non-termination of the inliner when handling certain negative recursive data types.
This section talks about the problem, but neglects to mention the all-important workaround: the inliner can be kept clear of a pathological binding by slapping a NOINLINE
pragma on it.
For the authors of the User's Guide this workaround may be something so obvious it doesn't bear mentioning, but to the readers that may not be the case. It's easy to instead assume—unconsciously—that there must be no solution when none are mentioned by the comprehensive, authoritative source.
The "Simplifier ticks exhausted" error message appears to be similarly flawed, going into some length about -fsimpl-tick-factor
and -funfolding-case-threshold
/scaling
while neglecting to mention NOINLINE
.
It does however refer the user to the Infelicities section, so it could be given a pass once that's fixed—I'm also unsure how appropriate a suggestion NOINLINE
would be for any other circumstances that could provoke the same error message.
While I'm here, there are a few less significant issues I may as well deal with:
- As I understand it, the example code is a demonstration of the unsoundness of negative recursive types by producing an obligate bottom.
This has mathematical significance, but in a programming context it's just an actively broken contrivance.
It's also poorly described by its introduction: "using the standard way to encode recursion via a data type".
To me, this instead suggests
fix
via the Y combinator, which isn't so contrived and is likely much better known to Haskellers. - The error message excerpt is from GHC 8.2.1, and while the details have not changed too dramatically, it's outdated nevertheless.
- Some awkward wording.
Proposed improvements or changes
I've rewritten the item in question here. The item's current form is the prior revision, so the diff can be easily examined.
N.B.
- I'm not an expert on GHC internals or technical writing; the rewrite should be reviewed for correctness, completeness, accidental misleads and tone.
- I don't know what flavour of markup the User's Guide is written in, so I've rendered it in (github) MarkDown—it will need to be translated back, with local links etc.
Environment
- GHC version used: 9.8.1alpha1 (compiler behaviour) / alpha3 (docs)