fix(walkvm): unwind through virtual thread continuation boundaries by jbachorik · Pull Request #450 · DataDog/java-profiler

jbachorik · 2026-03-31T10:43:10Z

What does this PR do?:
Fixes walkVM to correctly unwind through JVM virtual thread (Project Loom) continuation boundaries, exposing carrier thread frames in wall-clock profiles. Implements two unwind paths:

Path A (enterSpecial): CPU-bound VTs that never yield — all frames are thawed; the profiler traverses the enterSpecial nmethod by identity to reach carrier frames via ContinuationEntry.
Path B (cont_returnBarrier): Blocking VTs that park/unpark — when remounted with frozen frames still in the StackChunk, cont_returnBarrier is the return PC of the bottommost thawed frame. This is a JVM stub (not an nmethod), so it must be checked before CodeHeap::findNMethod().

By default, when a continuation boundary is reached the profiler inserts a synthetic "JVM Continuation" root frame (BCI_NATIVE_FRAME) and stops — the VT's own frames are complete and carrier internals are not profiling-relevant for most users. The sample is not marked truncated.

wextend=vt_carrier opt-in: power users can enable carrier frame walking via the new wextend argument. With wextend=vt_carrier the profiler walks through the continuation boundary to the carrier thread; any failure to do so emits a BCI_ERROR frame so the sample is truthfully marked truncated. Additional tokens may be added to wextend in the future for other stack-walk extensions.

Parent-chain walking via ContinuationEntry::_parent is supported for nested continuations (e.g. a Continuation.run() inside a VT, as used by Kotlin coroutines). Not triggered by standard single-level VTs today, but required once any JVM language runtime layers continuations on top of VTs.

Motivation:
Before this fix, wall-clock profiles of applications using Java 21+ virtual threads showed truncated stack traces — carrier thread frames (ForkJoinWorkerThread) were never visible. The root causes were:

cont_returnBarrier is a JVM stub, not in the nmethod table — the check was dead code placed after findNMethod().
enterSpecial detection was missing entirely.

Additional Notes:

DDPROF_DISABLE_CONT_UNWIND=1 env var disables both unwind paths at runtime (DEBUG builds only) for negative testing.
Three new counters: WALKVM_CONT_BARRIER_HIT, WALKVM_ENTER_SPECIAL_HIT, WALKVM_CONT_ENTRY_NULL.
Carrier frame pointer validation (isValidFP, isValidSP) guards all dereferences; any remaining SIGSEGV from stale pointers is caught by the existing setjmp crash protection in walkVM.
entryFP() layout: [ContinuationEntry bytes][carrier_fp][carrier_pc][carrier_sp...] — confirmed against OpenJDK source. Uses FRAME_PC_SLOT for architecture portability (ppc64 has FRAME_PC_SLOT=2).
VMContinuationEntry is split into DECLARE_V21_TYPES_DO (separate from DECLARE_TYPES_DO) so that verify_offsets() in DEBUG builds does not assert type_size() > 0 on JDK < 21.
carrier_frames feature bit added to StackWalkFeatures.

How to test the change?:
Integration tests: VirtualThreadWallClockTest covers both paths on JDK 21+ with wextend=vt_carrier:

samplesCarrierFramesFromCpuBoundVT — verifies Path A (enterSpecial)
samplesCarrierFramesFromBlockingVT — verifies Path B (cont_returnBarrier)

Both tests assert that ForkJoinWorkerThread carrier frames appear in at least one wall-clock sample from the virtual thread. Skipped on JDK < 21.

Unit tests: stackWalker_ut.cpp covers StackWalkValidation::isValidFP, isValidSP, and dropUnknownLeaf boundary conditions.

Run with: ./gradlew ddprof-test:testRelease (or testDebug if you want to check also the negative-test path).

For Datadog employees:

This PR doesn't touch any of that.
JIRA: SCP-1110

Fixes walkVM to correctly traverse JVM virtual thread (Project Loom) continuation boundaries, exposing carrier thread frames in wall-clock profiles. Two unwind paths are implemented: - Path A (enterSpecial): CPU-bound VTs that never yield — all frames are thawed; the profiler traverses the enterSpecial nmethod by identity to reach carrier frames via ContinuationEntry. - Path B (cont_returnBarrier): blocking VTs that park/unpark — when remounted with frozen frames in the StackChunk, cont_returnBarrier is the return PC of the bottommost thawed frame. Checked before CodeHeap::findNMethod() since it is a JVM stub, not an nmethod. By default a synthetic "JVM Continuation" root frame (BCI_NATIVE_FRAME) is inserted at the boundary so the sample is not marked truncated. With wextend=vt_carrier the profiler walks through to carrier frames; failures emit BCI_ERROR (truthful truncation). The wextend argument is string-parsed and extensible for future flags. Additional changes: - Add carrier_frames bit to StackWalkFeatures (uses one padding bit) - Use FRAME_PC_SLOT for architecture-portable carrier frame extraction - Split VMContinuationEntry into DECLARE_V21_TYPES_DO to prevent assert(type_size() > 0) on JDK <21 debug builds; expand at all four declare/init/read/verify sites - Three new counters: WALKVM_CONT_BARRIER_HIT, WALKVM_ENTER_SPECIAL_HIT, WALKVM_CONT_ENTRY_NULL - isValidFP / isValidSP helpers with unit tests in stackWalker_ut.cpp - DDPROF_DISABLE_CONT_UNWIND env var for negative testing (DEBUG only) - Integration tests: VirtualThreadWallClockTest covers both paths on JDK 21+ with wextend=vt_carrier Resolves SCP-1110 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dd-octo-sts · 2026-03-31T11:37:17Z

CI Test Results

Run: #23807620068 | Commit: 8e26957 | Duration: 26m 30s (longest job)

❌ 9 of 32 test jobs failed

Status Overview

JDK	glibc-aarch64/debug	glibc-amd64/debug	musl-aarch64/debug	musl-amd64/debug
8	-	✅	-	-
8-ibm	-	✅	-	-
8-j9	✅	✅	-	-
8-librca	-	-	✅	✅
8-orcl	-	✅	-	-
11	-	✅	-	-
11-j9	✅	✅	-	-
11-librca	-	-	✅	✅
17	✅	✅	-	-
17-graal	✅	✅	-	-
17-j9	✅	✅	-	-
17-librca	-	-	✅	✅
21	❌	❌	-	-
21-graal	❌	❌	-	-
21-librca	-	-	❌	✅
25	❌	✅	-	-
25-graal	❌	✅	-	-
25-librca	-	-	❌	❌

Legend: ✅ passed | ❌ failed | ⚪ skipped | 🚫 cancelled