Skip to content

perf: avoid per-node promises, closures and arrays in the validation walk - #2269

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

cdietrich merged 6 commits into
eclipse-langium:mainfrom
cdietrich:perf/2264-validation-walk

Conversation

@cdietrich

@cdietrich cdietrich commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #2264

DefaultDocumentValidator.validateAstNodes created a promise per AST node for await interruptAndCheck(), two async frames, two promises and a closure per node and check for the check wrapper, and a temporary children array per node. Almost all checks are synchronous, so nearly all of this was garbage.

With #2273 merged, the shared building blocks are already on main: interruptionDue(token) and its shared period check in promise-utils.ts, and AstUtils.pushChildrenInDocumentOrder. This PR now only changes the validator and the check wrapper.

Changes:

  • ValidationRegistry.wrapValidationException calls the check directly. The wrapped check returns undefined if the check returned anything that is not a thenable, and a promise if the check returned a thenable or threw. Errors still go through handleException, with the same message and logging, and OperationCancelled is still rethrown. A synchronous error is reported before the wrapper returns, as before.
  • validateAstNodes awaits interruptAndCheck only when interruptionDue is true, and awaits a check only if it returned something. It pushes the children of a node with pushChildrenInDocumentOrder, directly onto the stack, so it needs no temporary array.

What stays the same:

  • The nodes are visited in the same order, and validateSingleNodeOptions prunes the same subtrees.
  • The walk yields to the event loop at the same nodes, and it throws OperationCancelled at the next node after the token was cancelled.
  • Sync errors, async results, async rejections, non-Error throws and OperationCancelled (sync or async) are reported or passed on as before.
  • The profiled walk is unchanged.

Observable differences:

  • Between two real interruptions, the walk no longer goes through the microtask queue once per node and once per check. Other promise continuations therefore run at the interruption points rather than between nodes. That never gave the event loop a turn.
  • A subclass that overrides handleException still sees every error. It no longer sees successful synchronous checks. In the issue I asked whether that matters; routing the errors through handleException keeps the override point that matters for error reporting.
  • getChecks/getCheckArray return checks that may return undefined. Their type was MaybePromise<void> already. Code that calls .then on a check's result without checking would break; I found no such caller in this repository.

Tests: test/validation/document-validator-walk.test.ts: visit order with a node that has two child properties, and pruning; reporting of sync throws, async results, async rejections, async throws and string throws, with the walk continuing; an async check finishing before the next check and the next node; OperationCancelled thrown by a check, sync and async; cancellation during the walk; an event-loop turn during a 40 ms walk; the whole walk running without awaiting when all checks are synchronous (with CancellationToken.None and with a token while no interruption is due); the wrapper returning a promise only for async checks; errors going to an overridden handleException; OperationCancelled rethrown by the wrapper. All of them except the "without awaiting" ones and "returns a promise only if the check returned one" also pass on main, so they pin the existing behaviour; those three fail on main, so they guard the allocations. (The tests for interruptionDue and pushChildrenInDocumentOrder landed with #2273.)

Effect: measured on Langium 4.4.2 with a large DSL (details in #2264), the validator changes together with interruptionDue save about 1.5 GB of allocations per full pass (−17 %), with identical diagnostics. Rough benchmark numbers for main vs. this branch are in the comment below.

🤖 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
…walk

Fixes eclipse-langium#2264.

- `DefaultDocumentValidator.validateAstNodes` awaits `interruptAndCheck`
  only when `interruptionDue` says it would yield or throw. It yields and
  stops on cancellation at the same nodes as before.
- `ValidationRegistry.wrapValidationException` calls the check directly.
  The wrapped check returns a promise only if the check returned one or
  threw; errors still go through `handleException` and are reported as
  before, and `OperationCancelled` is still rethrown.
- The walk awaits a check only if it returned something, and pushes the
  children of a node directly onto the stack and reverses that part of the
  stack, instead of building a temporary array per node. The visiting
  order is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkvVhAAk5NRLH75qMHMc3m
cdietrich and others added 3 commits November 17, 2026 14:52
…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
Replaces the inline child-push block of `DefaultDocumentValidator.validateAstNodes`
with the shared internal helper. The visiting order 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).

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 19.4 s 247 GB (−1.5 %) 3,916 14.7 s

The gain is 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, which is not per-node overhead. The −17 % in #2264 was measured on a workspace with much more validation per AST node, where the per-node promises and closures make up a larger share.

🤖 Generated with Claude Code

@msujew

msujew commented Nov 18, 2026

Copy link
Copy Markdown
Member

I'll have a closer look at this once #2273 lands, that should reduce noise from the changes.

…walk

# Conflicts:
#	packages/langium/test/utils/ast-walk.test.ts
@cdietrich
cdietrich requested a review from msujew November 18, 2026 11:31

@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 to me 👍

@cdietrich
cdietrich merged commit f659757 into eclipse-langium:main Nov 18, 2026
4 checks passed
@cdietrich
cdietrich deleted the perf/2264-validation-walk branch November 18, 2026 11:39
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-node promise, closure and array allocations in the validation walk

2 participants