Skip to content

perf: avoid per-node promises, streams and iterators when linking and indexing references - #2273

Merged
cdietrich merged 6 commits into
eclipse-langium:mainfrom
cdietrich:perf/link-index-walk
Nov 18, 2026
Merged

cdietrich merged 6 commits into
eclipse-langium:mainfrom
cdietrich:perf/link-index-walk

Conversation

@cdietrich

@cdietrich cdietrich commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Refs #2264 (same pattern, in the linker and the reference index)

Contains the first three commits of #2269 (interruptionDue, the shared interruption period check, and pushChildrenInDocumentOrder), so it can land first; #2269 then only adds the validation walk on top.

DefaultLinker.link and DefaultReferenceDescriptionProvider.createDescriptions both run this loop over every document:

for (const node of streamAst(root)) {
    await interruptAndCheck(cancelToken);
    streamReferences(node).forEach(...);
}

For every AST node that costs a promise and an async resumption, two Object.keys arrays, two streams with their closures and iterator state, and an iterator result per child and per reference. A document build runs it twice per document.

Changes:

What stays the same:

  • The same references, containers, properties and indices, in the same order; inherited and $-prefixed properties are skipped as with Object.keys and streamReferences.
  • Yielding to the event loop and OperationCancelled at the same nodes as before. The remaining references of the node where the token was cancelled are still visited, as with streamReferences(node).forEach.

One assumption: the walk reads the children of a node when it visits the node, after the callback ran for the node's references. streamAst reads each child only once the subtree of the previous child is done. The order is therefore the same as long as the callback doesn't add, remove or replace contained AST nodes. Linking and indexing don't; the JSDoc of walkReferences states it as a requirement for action.

Tests (test/utils/walk-references.test.ts), on a grammar with single references, reference arrays, a multi-reference and nested nodes. The test imports walkReferences, and everything it combines it with, from the sources, so that all of them share one instance of promise-utils:

  • walkReferences and pushChildrenInDocumentOrder are part of AstUtils;
  • the same ReferenceInfos in the same order as the streamAst loop, for the root and for every subtree;
  • inherited and $-prefixed properties are skipped, as by the streamAst loop;
  • the whole walk runs without awaiting with CancellationToken.None and with a token while no interruption is due;
  • OperationCancelled before the first reference for a cancelled token, and at the next node when the token is cancelled during the walk;
  • an event-loop turn during a 40 ms walk;
  • DefaultLinker links every reference once, in the streamAst order, to the expected targets; DefaultReferenceDescriptionProvider creates the same descriptions in the same order as with the streamAst loop; both stop on cancellation.

The linker and provider tests don't use walkReferences and also pass on main.

Effect: in a workspace of 9,795 documents of a large Langium DSL (Langium 4.4.2, the same walk as a service override), the full build allocated 1,549 MB less while linking and 1,545 MB less while indexing references, with identical link targets and diagnostics.

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

🤖 Generated with Claude Code

https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m

cdietrich and others added 2 commits November 17, 2026 13:14
`interruptAndCheck` is async, so every call creates a promise and every
await costs a microtask, although it only yields once per interruption
period and only throws once the token is cancelled. `interruptionDue`
evaluates the same conditions synchronously, so that loops can await
`interruptAndCheck` only when it would yield or throw.

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

`DefaultLinker.link` and `DefaultReferenceDescriptionProvider.createDescriptions`
walked the AST with `streamAst`, awaited `interruptAndCheck` for every node and
streamed its references with `streamReferences`. That costs a promise, two
`Object.keys` arrays, two streams and an iterator result per child and per
reference for every AST node, twice per document build.

The new `AstUtils.walkReferences` visits the same references in the same order
with an explicit stack, awaits `interruptAndCheck` only when `interruptionDue`
says it would yield or throw, and allocates only the `ReferenceInfo` per
reference. It reads the children of a node when the node is visited, so the
callback must not add, remove or replace contained AST nodes; linking and
indexing don't. The profiled path of `link` is unchanged.

The same pattern as in the validation walk (eclipse-langium#2264).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m
@cdietrich
cdietrich marked this pull request as ready for review November 17, 2026 12:49
cdietrich and others added 3 commits November 17, 2026 14:55
…d interruptionDue

Both functions now read the "interruption period elapsed" condition from
one private helper, so that they can't drift apart. `interruptAndCheck`
behaves as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m
…ode in document order

`pushChildrenInDocumentOrder` pushes the children of a node onto an explicit
stack and reverses that part of the stack, so that they are popped in the
order of `streamContents`, without a temporary array. It is meant for the
stack-based walks of the validator and, later, the linker and the reference
index, so that they share one implementation.

The helper lives in the new module `utils/ast-walk.ts`, which is not
re-exported from `utils/index.ts`, so it does not become part of `AstUtils`
or the public API.

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

`walkReferences` moves from `ast-utils.ts` to the new module
`utils/walk-references.ts`, which is not re-exported from `utils/index.ts`.
So it is no longer part of `AstUtils`, and its restriction that `action` must
not add, remove or replace contained AST nodes doesn't become public API.
`DefaultLinker` and `DefaultReferenceDescriptionProvider` import it from there.

It now pushes the children of a node with the shared internal helper
`pushChildrenInDocumentOrder`, like the validation walk. The order of the
visited references is unchanged.

The tests import `walkReferences` and everything they combine it with from
the sources, so that they share one instance of `promise-utils`.

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).

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 GC
main 18.7 s 250 GB 3,978 15.1 s
this branch 18.5 s 240 GB (−4 %) 3,816 14.9 s

Small in this benchmark, and the time difference is within its noise (about ±3 % between runs). Each of its builds allocates about 41 GB and takes about 19 s, mostly because of the deliberately unresolved references; the walk itself is a small share of that. On a workspace where linking and indexing visit many more AST nodes per reference, the two removed per-node loops were about 1.5 GB per full build each (see the description).

🤖 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, implementation looks good, just some comments on API - the functions currently are not usable by adopters of Langium.

Comment thread packages/langium/src/utils/ast-walk.ts Resolved
…tUtils

Both helpers were kept in internal modules, so adopters could not use them. Move them into
ast-utils.ts, so that they are exported through AstUtils, and drop the internal ast-walk.ts and
walk-references.ts modules.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m
@cdietrich
cdietrich merged commit 2ace1cd into eclipse-langium:main Nov 18, 2026
4 checks passed
@cdietrich
cdietrich deleted the perf/link-index-walk branch November 18, 2026 11:31
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.

2 participants