docs: Notes for IR annotations, inlining, and newtype erasure (#44)#129
Merged
Conversation
Add GHC-style Notes for three IR invariants and cite them from their dependent sites. Comments only; generated code and goldens unchanged. - Note [Inline annotations and inlining heuristics] (IR.Inliner): the pragma -> annotation map -> Ann -> optimizer-decision flow, plus the linker's synthesised Inline.Always on foreign wrappers. - Note [Inliner annotations must all be consumed] (Backend.IR): the annotation map is linear; runRepM reports leftovers, which is how a typo'd pragma is caught. - Note [Newtype constructors are erased] (Backend.IR): the three isNewtype sites (construction identity, application unwrap, matching skip). The Ref Index type now points at the existing Note [Sequential scoping of Let bindings], which already covers the per-name De Bruijn scheme. Continues #44.
There was a problem hiding this comment.
Pull request overview
This PR continues the repo’s “GHC-style Note” documentation effort (#44) by adding and cross-referencing several Note [..] blocks that explain load-bearing IR invariants (inliner annotations as a linear resource, the end-to-end path of @inline pragmas into optimizer decisions, and newtype constructor erasure). The intent is to make these invariants easier to audit and keep consistent across producer/consumer sites without changing compiler behavior.
Changes:
- Added
Note [Inline annotations and inlining heuristics](plus call-siteSee Notereferences) describing how@inlineannotations flow from module comments intoAnnand into inlining decisions. - Added
Note [Inliner annotations must all be consumed]and referenced it fromparseAnnotations/useAnnotationto document the “no leftovers” validation enforced byrunRepM. - Added
Note [Newtype constructors are erased]and referenced the three keyisNewtypesites (construction/application/matching), plus aSee Notepointer forIndex.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| lib/Language/PureScript/Backend/IR/Types.hs | Adds a See Note pointer clarifying what Index selects. |
| lib/Language/PureScript/Backend/IR/Optimizer.hs | Adds a See Note pointer from isInlinableExpr to the new inliner-annotation Note. |
| lib/Language/PureScript/Backend/IR/Linker.hs | Adds a See Note pointer documenting the linker’s synthesized Inline.Always usage for foreign wrappers. |
| lib/Language/PureScript/Backend/IR/Inliner.hs | Introduces Note [Inline annotations and inlining heuristics] describing the pragma→map→Ann→optimizer pipeline. |
| lib/Language/PureScript/Backend/IR.hs | Introduces Notes documenting annotation consumption and newtype erasure, with See Note references at relevant sites. |
| changelog.d/20260625_201941_unisay_notes_ir_inliner.md | Adds a changelog fragment describing the documentation additions. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Continues #44, the IR/inliner batch. Three more invariants get a GHC-style
Note, each cited from its dependent sites. Comments only, so generated code, goldens, and eval oracles are unchanged.Note [Inline annotations and inlining heuristics]inIR.Inliner. Traces an@inlinepragma from a module comment throughparseAnnotations, the annotation map,useAnnotation, and the expressionann, toOptimizer.isInlinableExprreading it back withgetAnn. Also notes the linker's synthesisedInline.Alwayson foreign-field wrappers. Cited from the optimizer and linker sites.Note [Inliner annotations must all be consumed]inBackend.IR. The annotation map is a linear resource: filled byparseAnnotations, drained byuseAnnotation, and checked empty byrunRepM, which errors on leftovers. That check is what turns a typo'd or misplaced pragma into a reported error instead of a silent no-op.Note [Newtype constructors are erased]inBackend.IR. One convention across threeisNewtypesites: construction is identity (mkConstructor), application unwraps (mkApplication), and matching skips the constructor (mkBinder). Only the matching half was hinted at before.A note on the De Bruijn item
The issue also lists "namespaced De Bruijn indices" and suggests folding it into the existing
Note [Sequential scoping of Let bindings]. That Note already opens with the per-name index scheme, so rather than duplicate it I just pointed theIndexnewtype at it with aSee Note.Checklist
changelog.d/fragment for any user-facing change (scriv createin the dev shell), or this change ships nothing releasable (CI, docs, or an
internal refactor).
nix develop),fourmolu -i lib/ exe/ test/andhlint lib/ exe/ test/are clean.cabal test allpasses; structural goldens werere-accepted on purpose if codegen moved (
PSLUA_GOLDEN_ACCEPT=1), andeval/golden.txtstill holds.