Skip to content

perf: avoid per-invocation allocations in the parser builder and value converter - #2268

Merged
cdietrich merged 4 commits into
eclipse-langium:mainfrom
cdietrich:perf/2262-parser-allocations
Nov 17, 2026
Merged

cdietrich merged 4 commits into
eclipse-langium:mainfrom
cdietrich:perf/2262-parser-allocations

Conversation

@cdietrich

@cdietrich cdietrich commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #2262

The parser builder allocated throwaway objects and closures every time a grammar element ran, not once per grammar element. DefaultValueConverter allocated two strings per converted token. This PR removes both. There are two commits: the parser builder, then the value converter.

Parser builder (parser-builder-base.ts, langium-parser.ts)

  • Options built once per grammar site. Alternatives, *, +, ?, guarded groups, unordered groups and infix rules used to build a new Chevrotain options object (or array of alternatives) and new ALT/DEF/GATE closures on every call, only so the closures could capture args. Now the options are built once, when the parser is built. Their callbacks read args from a slot that belongs to that site. A small helper, withArgsSlot, sets the slot for the duration of the call and restores the previous value in a finally.
  • Rule calls without arguments share one frozen EMPTY_ARGS object instead of allocating {} per call.
  • ChevrotainWrapper.wrapSubrule reuses one { ARGS: [args] } object per wrapper instead of allocating it per call.
  • buildGroup iterates with for...of instead of creating a forEach closure per call.
  • assignWithoutOverride uses for...in with an own-property check instead of Object.entries, the same pattern as perf: remove per-node allocations on the parse and validation hot paths #2234.

The issue's prototype covered alternatives, * and ?. This PR uses the same approach for + (with and without a guard), guarded groups without a cardinality, unordered groups and infix rules, because they had the same per-call allocation.

Value converter (value-converter.ts)

runConverter called rule.name.toUpperCase() and, for most rules, getRuleType(rule)?.toLowerCase() for every converted token. The result only depends on the rule, so it is now computed once per rule and cached in the converter: DefaultValueConverter gets a protected converterKinds map plus protected getConverterKind and computeConverterKind methods, so subclasses can reuse or override the caching and the decision (new exported type ValueConverterKind). The order of the checks is unchanged: first the rule name (INT, STRING, ID, case-insensitive), then the rule type (number, boolean, bigint, date, case-insensitive), otherwise the input is returned unchanged. Subclasses that override runConverter are not affected.

Why the behaviour is unchanged

  • Chevrotain calls ALT, DEF and GATE synchronously, inside the or/many/option/atLeastOne call that our method makes. The slot holds the current call's args for exactly that time. In-repetition error recovery re-enters many/atLeastOne synchronously too, so it also sees the right args.
  • Re-entrancy: when a rule call inside a loop reaches the same grammar site again (recursion), the inner call overwrites the slot and restores it on exit. The outer loop's next GATE/DEF then reads its own arguments again. The finally also restores the slot when a recognition exception propagates.
  • subruleInternal reads options.ARGS and spreads it into coreRule.apply(this, args) straight away. Only LABEL is read from the options afterwards, and the recorder only reads LABEL as well. So one options object can be reused even for nested subrule calls.
  • The lookahead functions (chevrotain-allstar and LL(k)) read GATE from the passed alternatives on each call and do not cache anything by the identity of the options. So reusing the same options object changes nothing there.
  • The option objects keep the same shape as before: GATE is only set on alternatives that have a guard, and GATE: undefined is still passed for */? without a guard. As a result, Chevrotain's recording (hasPredicates) sees the same grammar.

Behaviour change (for the changelog)

Rule calls without arguments now share one frozen EMPTY_ARGS object; before, each got a fresh {}. Code outside Langium that writes to these arguments (custom parser builder code, overridden predicates) used to work and now throws a TypeError, since ES modules run in strict mode. Langium itself never writes to args, so this only affects such custom code, but it is visible to adopters.

Tests

  • langium-parser-builder.test.ts, new block "Rule arguments in nested and recursive rule calls". Its grammar has one rule per construct (alternatives in *, alternatives in +, guarded *, guarded +, guarded ?, guarded group, unordered group, infix rule). Each rule flips a boolean parameter on every nesting level, and a keyword is only accepted for one value of it. The inputs nest each construct in itself and keep parsing the outer construct after the nested one returns. For valid and invalid inputs, the tests check the AST (all properties), the CST (each token with the depth of the AST node it belongs to) and the exact parser errors (offset and message), including the AST and CST after error recovery. The expected values were produced with the code on main, and the tests pass both on main and on this branch. A further test parses a valid input, then an invalid one, then the valid one again, and expects the same result.
  • value-converter.test.ts, new block for runConverter. It covers every rule kind: by name (INT, STRING, ID, and the mixed-case Int, String, Id), by explicit type (terminal and data type rule), by implicit type (a rule named Number or Boolean), and no conversion. Each case is checked on a repeated call, on a fresh converter instance, and with several rules mixed through one instance. It also pins that the name takes precedence over the type: Int returns number converts 4.5 to 4.

Mutation checks. Each change was applied on its own, the package was rebuilt, and packages/langium/test/parser/ was run:

Mutation Result
no restore in withArgsSlot (all sites) 8 tests fail
no restore only for * / + / guarded + / infix 3 / 2 / 2 / 1 tests fail
* DEF, alternatives GATE, unordered GATE, ? GATE or infix operand reads EMPTY_ARGS instead of the slot 6 / 24 / 3 / 2 / 1 tests fail
slot set only on the first call 12 tests fail
wrapSubrule doesn't set ARGS[0] 39 tests fail
assignWithoutOverride skips every property 2 tests fail
converter: case-sensitive name check / type checked before name / one cached kind for all rules 3 / 1 / many tests fail
no restore only for alternatives, ?, guarded group or unordered group not detected
no own-property check in assignWithoutOverride not detected

The undetected restores are expected. For those sites Chevrotain reads GATE/ALT/DEF only before any nested call, and the enclosing site sets the slot again on every entry. So during normal parsing nothing reads a stale slot. The restore stays for uniformity and so the code doesn't depend on that. The own-property check matches Object.entries exactly, but the parser only passes plain object literals there, so it makes no difference in practice.

npm run build, npm run lint and npm test -- packages/langium/ pass (62 files, 1165 tests).

Effect

From the issue, measured on Langium 4.4.2 with a 7,137-document workspace: one full parse allocates about 1.65 GB before and about 0.96 GB after (−40 %). ASTs, CSTs and errors are byte-identical.

Benchmark numbers for main vs. this branch will follow in a comment.

The change cuts garbage, not retained memory, so cst-parse-memory-benchmark.ts is not expected to change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m

cdietrich and others added 3 commits November 17, 2026 13:19
…-langium#2262)

The methods built for alternatives, `*`, `+`, `?`, guarded groups, unordered
groups and infix rules allocated a new Chevrotain options object (or array of
alternatives) and new `ALT`/`DEF`/`GATE` closures on every invocation, only to
capture the rule arguments. The options are now built once per grammar site.
Their callbacks read the arguments from a slot of that site, which the method
sets for the duration of the call and restores afterwards, so a recursive
invocation of the same site does not affect the outer one. Chevrotain calls
the callbacks synchronously within the call.

Also:
- rule calls without arguments share one frozen empty arguments object
  instead of allocating `{}` per call
- `ChevrotainWrapper.wrapSubrule` reuses one `{ ARGS: [args] }` object;
  Chevrotain spreads `ARGS` into the rule invocation synchronously
- `buildGroup` iterates with `for...of` instead of a `forEach` closure
- `assignWithoutOverride` uses `for...in` with an own-property check instead
  of `Object.entries`

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m
…ipse-langium#2262)

`runConverter` called `rule.name.toUpperCase()` and, for most rules,
`getRuleType(rule)?.toLowerCase()` for every converted token. Both allocate a
new string, although the result only depends on the rule. The decision is now
computed once per rule and cached in a WeakMap. The precedence (rule name
INT/STRING/ID first, then the rule type) is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m
@cdietrich

Copy link
Copy Markdown
Contributor Author

Rough benchmark numbers for this branch vs. main (da1beac): Node 24 on a laptop that wasn't idle, so ballpark figures rather than a careful benchmark. Allocation, scavenges and GC time are process totals, recorded with a small --import preload using v8.GCProfiler (allocation estimated as the heap before each GC minus the heap after the previous one).

packages/langium/test/parser/parser-time-benchmark.ts (~1.5 MB input, 30 measured parses; totals include 10 warm-up parses and 10 lexer runs), 2 runs each:

median parse allocated scavenges GC
main 625 ms 38.7 GB 629 8.5 s
this branch 390 ms (−38 %) 14.6 GB (−62 %) 262 (−58 %) 8.2 s

examples/statemachine/test/workspace-build-benchmark.ts (100 documents, ~10 MiB, 5 measured builds; totals over all 6 builds), one run each:

build median allocated scavenges
main 18.7 s 250 GB 3,978
this branch 19.0 s 249 GB (−0.4 %) 3,960

The workspace benchmark spends most of its time in linking and validation, so the parser saving barely shows there; its build times vary by about ±3 % between runs.

🤖 Generated with Claude Code

@msujew msujew left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, looks good. Just one suggestion, see below.

As suggested in review: the cache and the functions that compute it move into the class
(`converterKinds`, `getConverterKind`, `computeConverterKind`, all protected), so subclasses can
reuse or override them. Since the cache now lives as long as the converter, it is a plain Map.
The kind type is exported as ValueConverterKind for the protected signatures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m
@cdietrich
cdietrich merged commit 9ee3a40 into eclipse-langium:main Nov 17, 2026
4 checks passed
@cdietrich
cdietrich deleted the perf/2262-parser-allocations branch November 17, 2026 15:59
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.

Perf: per-invocation allocations in the parser builder and value converter

2 participants