Skip to content

feat: add a whole-program optimizing compiler section to the front page - #223

Merged
magnus-madsen merged 4 commits into
masterfrom
feat/optimizing-compiler-section
Aug 10, 2026
Merged

feat: add a whole-program optimizing compiler section to the front page#223
magnus-madsen merged 4 commits into
masterfrom
feat/optimizing-compiler-section

Conversation

@magnus-madsen

@magnus-madsen magnus-madsen commented Aug 10, 2026

Copy link
Copy Markdown
Member

Adds a section to the front page showing what the compiler does to the code it generates — built around a worked example and the bytecode actually emitted for it, rather than a list of claims.

The figure

def sumWith(f: a -> Int32, arr: Array[a, r]): Int32 \ r =
    Array.foldLeft((acc, x) -> acc + f(x), 0, arr)

def main(): Unit \ IO =
    region rc {
        let arr = Array#{1, 2, 3, 4, 5} @ rc;
        println(sumWith(x -> x * x, arr))
    }

A polymorphic, higher-order fold over a mutable array in a region compiles to a 34-byte counted loop taking a bare int[] and three raw ints, with the lambda reduced to a single imul and the recursion to goto 0.

Every claim beside the listing was verified against a real build with flix 0.75.2:

  • No closure allocation — no Clo$main$* class is emitted at all, so neither sumWith nor the lambda survives as a closure.
  • No recursionArray.foldLeft is recursive; the emitted code ends in goto 0.
  • No boxing — the loop signature is (int[], int, int, int); only the final result is boxed.
  • No dispatch — the loop body's entire opcode inventory is loads, stores, arithmetic and branches. No invoke, new, or newarray.

The listing elides only the trailing boxing of the result. The loop body has no constant-pool references at all, so it is otherwise verbatim javap output plus comments, reproducible with flix build followed by javap -c -p.

Placement and framing

It sits after "Compiler Performance: The Raw Numbers", so the compiler region reads architecture → compiler speed → generated-code quality. That section already claims the compiler is fast "despite supporting costly features, including monomorphization and whole-program optimization" without ever saying what those are; the new section's title and lead now name them.

How the example was chosen

Three variants were built and disassembled before settling on the region-based one:

classes jar loop signature allocation in loop
List 172 83K (int, Tagged$) none in the fold
Vector 169 80K (int, int, int) newarray every iteration
region Array 165 78K (int[], int, int, int) none

The region version wins on every axis, and earns a claim the others can't: the region has no runtime representation in the loop — main allocates a Region$, but the loop receives a plain array.

magnus-madsen and others added 3 commits August 10, 2026 13:11
Adds a section to the front page covering what the compiler does to the
code it generates: monomorphization, inlining, dead code elimination,
compile-time pattern matching, lambda dropping, tree shaking, and tail
call elimination.

It sits after "Compiler Performance: The Raw Numbers" so the compiler
region reads architecture -> compiler speed -> generated-code quality.
That section already claims the compiler is fast "despite supporting
costly features, including monomorphization and whole-program
optimization" without ever saying what those are; this explains them.

Each bullet leads with the technical name but explains it in terms of
the code the reader writes rather than the transformation the compiler
performs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Seven bullets at full width made a tall, thin block quite unlike the
three-column Complete Feature List above it. Splits them across two
col-md-6 columns, following the row structure that section already uses:
the heading and lead span col-md-12, the lists sit in sibling columns,
and the closing paragraph spans the full width again.

Split 3+4 rather than 4+3. The first three bullets carry about half the
text between them, so an even count would leave the left column
noticeably longer; reading order down the left and then the right is
the same either way.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replaces the seven prose bullets with a worked example and the bytecode
the compiler actually emits for it. A polymorphic, higher-order fold over
a mutable array in a region compiles to a 34-byte counted loop over a
bare int[], with the lambda reduced to a single imul.

Every claim beside the listing was verified against a real build with
flix 0.75.2:

  - no Clo$main$* class is emitted, so neither sumWith nor the lambda
    survives as a closure;
  - the loop body's entire opcode inventory is loads, stores, arithmetic
    and branches -- no invoke, new, or newarray;
  - the array is allocated once in main, outside the loop.

The listing elides only the trailing boxing of the result. The loop body
has no constant-pool references at all, so it is otherwise verbatim
javap output plus comments.

Retitles the section to name whole-program optimization, which the
performance section directly above already claims without explaining,
and drops the reference to JVM bytecode from the lead in favour of the
optimizations themselves.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@magnus-madsen magnus-madsen changed the title feat: describe the optimizing compiler on the front page feat: add a whole-program optimizing compiler section to the front page Aug 10, 2026
@magnus-madsen
magnus-madsen marked this pull request as ready for review August 10, 2026 13:30
"Write code in whatever style you prefer" is a broad promise, and the
four bullets beside it are each carefully scoped to one worked example.
Marks the claim with an asterisk and answers it below the bullets, in
the same muted style as the reproduce note in the opposite column.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@magnus-madsen
magnus-madsen merged commit c7f4530 into master Aug 10, 2026
2 checks passed
@magnus-madsen
magnus-madsen deleted the feat/optimizing-compiler-section branch August 10, 2026 13:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant