Add stack-safe async loop support with trampoline pattern by vbabanin · Pull Request #1905 · mongodb/mongo-java-driver

vbabanin · 2026-03-04T21:06:01Z

Add AsyncTrampoline class to prevent stack overflow in loops by converting callback recursion into iterative execution
Add thenRunWhileLoop method to AsyncRunnable to support while-loop semantics where condition is checked before body execution
Integrate trampoline into AsyncCallbackLoop by making LoopingCallback implement Runnable to avoid per-iteration lambda allocation

- Add AsyncTrampoline class to prevent stack overflow in loops by converting callback recursion into iterative execution - Add thenRunWhileLoop method to AsyncRunnable to support while-loop semantics where condition is checked before body execution - Integrate trampoline into AsyncCallbackLoop by making LoopingCallback implement Runnable to avoid per-iteration lambda allocation JAVA-6120

vbabanin · 2026-03-06T23:56:18Z

driver-core/src/main/com/mongodb/internal/async/function/AsyncCallbackLoop.java


        LoopingCallback(final SingleResultCallback<Void> callback) {
            wrapped = callback;
+            nextIteration = () -> body.run(this);


The nextIteration is reused to avoid creation of extra objects via LambdaMetafactory as we have the capturing lambda.

bounce.work = task is a write to a heap object's field, which can be considered an automatic escape in the JIT's analysis. Even if the Bounce object is short-lived, the JIT sees "object written to another object's field" and should give up.

The AsyncCallbackLoop JMH GC profiling (OpenJDK 17.0.10 LTS, 64-bit Server VM, mixed mode with compressed oops).

Metric Runnable (this) Lambda

Alloc rate 0.039 MB/sec 96.924 MB/sec

Alloc per op 64 B/op 160,048 B/op

GC count ~ 0 10

GC time 0 ms 9 ms

For Lambda case:
Per iteration: 1 lambda * 16 bytes = 16 B

Per op (10,000 iterations): 10,000 * 16 = 160,000 B

Plus one-time objects ~ 48 B

Copilot

Pull request overview

This PR introduces stack-safe async looping by adding a trampoline mechanism and extending the internal async chaining API with pre-check while-loop semantics.

Changes:

Added AsyncTrampoline to convert re-entrant callback recursion into iterative execution (stack-safe loop continuations).
Added AsyncRunnable.thenRunWhileLoop(...) for while (condition) { body } semantics in async chains.
Updated AsyncCallbackLoop to use the trampoline and avoid per-iteration lambda allocation; expanded unit tests to cover while/do-while behavior and nested loops.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
driver-core/src/main/com/mongodb/internal/async/AsyncTrampoline.java	New trampoline utility to flatten re-entrant async loop continuations and keep stack depth constant.
driver-core/src/main/com/mongodb/internal/async/function/AsyncCallbackLoop.java	Routes loop continuation through `AsyncTrampoline.run(...)` and caches the “next iteration” runnable.
driver-core/src/main/com/mongodb/internal/async/AsyncRunnable.java	Adds `thenRunWhileLoop` API to express while-loops in async chains.
driver-core/src/test/unit/com/mongodb/internal/async/AsyncFunctionsAbstractTest.java	Adds tests for while-loop semantics, nested loops, and stack-depth invariance checks.
driver-core/src/test/unit/com/mongodb/internal/async/AsyncFunctionsTestBase.java	Enhances assertion messaging when sync/async exception presence diverges.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-21T01:25:34Z

driver-core/src/test/unit/com/mongodb/internal/async/AsyncFunctionsTestBase.java

+                format("both or neither should have produced an exception. Expected exception: %s, actual exception: %s",
+                        expectedException,
+                        actualException));


The assertion message formats actualException (the AtomicReference) instead of the stored throwable (actualException.get()), so failures will print something like AtomicReference@... rather than the actual exception. Pass actualException.get() to format (and consider also including expectedException.getClass()/actualException.get().getClass() if helpful).

Suggested change

format("both or neither should have produced an exception. Expected exception: %s, actual exception: %s",

expectedException,

actualException));

format("both or neither should have produced an exception. "

+ "Expected exception: %s (%s), actual exception: %s (%s)",

expectedException,

expectedException == null ? null : expectedException.getClass(),

actualException.get(),

actualException.get() == null ? null : actualException.get().getClass()));

agree with copilot here , actualException is atomic reference that gives throwable, I think we should replace it with actualException.get

I have changed it to use actualException.get(). However, what Copilot suggested with ternary logic is not correct, because expectedException.getClass() will provide less details than using toString on the exception.

driver-core/src/main/com/mongodb/internal/async/AsyncRunnable.java

driver-core/src/test/unit/com/mongodb/internal/async/AsyncFunctionsAbstractTest.java

…java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

driver-core/src/main/com/mongodb/internal/async/function/AsyncCallbackLoop.java

strogiyotec · 2026-03-29T05:00:42Z

driver-core/src/test/unit/com/mongodb/internal/async/AsyncFunctionsAbstractTest.java

+        assertEquals(depthWith100, depthWith10000, "Stack depth should be constant regardless of iteration count (trampoline)");
+    }
+
+    private int maxStackDepthForIterations(final int iterations) {


can we move this method below all other test cases
so that we preserve the order

tests first

utility + private method second

I agree that separating utilities from tests is useful in general. However, these methods each have exactly one caller (the test directly above). I kept them inline for locality so the reader sees the test and its implementation detail together without scrolling. The codebase doesn't enforce a strict ordering convention - CrudProseTest.java#L357 and several other test classes use the same inline approach.

strogiyotec · 2026-03-29T05:02:48Z

driver-core/src/test/unit/com/mongodb/internal/async/AsyncFunctionsTestBase.java

+                format("both or neither should have produced an exception. Expected exception: %s, actual exception: %s",
+                        expectedException,
+                        actualException));


agree with copilot here , actualException is atomic reference that gives throwable, I think we should replace it with actualException.get

…CallbackLoop.java Co-authored-by: Almas Abdrazak <almas337519@gmail.com>

JAVA-6120

vbabanin self-assigned this Mar 4, 2026

vbabanin added 3 commits March 4, 2026 13:28

Fis SpotBugs concern.

cfef056

Remove unused imports.

9d38e5f

Remove redundant comments.

62f4bb3

vbabanin commented Mar 6, 2026

View reviewed changes

Rename classes.

7d9bf06

vbabanin marked this pull request as ready for review March 7, 2026 00:13

vbabanin requested a review from a team as a code owner March 7, 2026 00:13

vbabanin requested review from nhachicha, stIncMale and strogiyotec and removed request for nhachicha March 7, 2026 00:13

vbabanin and others added 2 commits March 16, 2026 21:03

Merge branch 'main' into JAVA-6120

76f5f13

Merge branch 'main' into JAVA-6120

dbbe307

katcharov requested a review from Copilot March 21, 2026 01:20

Copilot started reviewing on behalf of katcharov March 21, 2026 01:21 View session

Copilot AI reviewed Mar 21, 2026

View reviewed changes

Update driver-core/src/main/com/mongodb/internal/async/AsyncRunnable.…

4c7f0de

…java Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

strogiyotec previously approved these changes Mar 29, 2026

View reviewed changes

Update driver-core/src/main/com/mongodb/internal/async/function/Async…

ecb7ad8

…CallbackLoop.java Co-authored-by: Almas Abdrazak <almas337519@gmail.com>

vbabanin dismissed strogiyotec’s stale review via ecb7ad8 April 8, 2026 06:22

Merge branch 'main' into JAVA-6120

016aad9

vbabanin requested a review from strogiyotec April 9, 2026 03:41

Use explicit reference.

5114a5e

JAVA-6120

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add stack-safe async loop support with trampoline pattern#1905

Add stack-safe async loop support with trampoline pattern#1905
vbabanin wants to merge 11 commits intomongodb:mainfrom
vbabanin:JAVA-6120

vbabanin commented Mar 4, 2026 •

edited

Loading

Uh oh!

vbabanin Mar 6, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 21, 2026

Uh oh!

strogiyotec Mar 29, 2026

Uh oh!

vbabanin Apr 8, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

strogiyotec Mar 29, 2026

Uh oh!

vbabanin Apr 9, 2026 •

edited

Loading

Uh oh!

strogiyotec Mar 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Metric	Runnable (this)	Lambda
Alloc rate	0.039 MB/sec	96.924 MB/sec
Alloc per op	64 B/op	160,048 B/op
GC count	~ 0	10
GC time	0 ms	9 ms

-                format("both or neither should have produced an exception. Expected exception: %s, actual exception: %s",
-                        expectedException,
-                        actualException));
+                format("both or neither should have produced an exception. "
+                                + "Expected exception: %s (%s), actual exception: %s (%s)",
+                        expectedException,
+                        expectedException == null ? null : expectedException.getClass(),
+                        actualException.get(),
+                        actualException.get() == null ? null : actualException.get().getClass()));

Conversation

vbabanin commented Mar 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vbabanin Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 21, 2026

Choose a reason for hiding this comment

Uh oh!

strogiyotec Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

vbabanin Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

strogiyotec Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

vbabanin Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

strogiyotec Mar 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vbabanin commented Mar 4, 2026 •

edited

Loading

vbabanin Mar 6, 2026 •

edited

Loading

vbabanin Apr 9, 2026 •

edited

Loading