Virtual thread API migration failures from JDK 19/20 preview to JDK 21 final

Question

Goal: diagnose why code that compiled and ran with the preview virtual thread API in JDK 19 or JDK 20 fails when compiled or executed on JDK 21, where virtual threads are finalized and the API has changed.
Constraints: the code may use preview‑only imports (jdk.incubator.concurrent), preview‑only constructors, and custom scheduler implementations that relied on preview‑only classes; there is uncertainty about which preview methods were removed, what their replacements are, and how refined thread‑pinning behavior in the final release affects libraries that synchronize or call native code.
End with specific questions:

Which preview‑only virtual‑thread methods (e.g., Thread.startVirtualThread) were removed or renamed in the final API, and what are the recommended replacements?
What adaptation is needed for custom scheduler code to work with the final virtual‑thread API, especially regarding removal of the preview‑only FiberScheduler interface?
What adjustments are needed to avoid thread‑pinning warnings when using the final virtual‑thread API with libraries that hold monitors or invoke native methods?

Muntasir · Answer

Confirmed API Changes in JDK 21
The virtual thread API has been finalized in JDK 21 with the following key changes:

Package relocation: All virtual thread APIs moved from jdk.incubator.concurrent to standard packages java.lang and java.util.concurrent.
Thread.startVirtualThread(): Now a standard method in java.lang.Thread that no longer requires preview flags.
FiberScheduler removal: The preview-only FiberScheduler interface was removed entirely.

Migration Steps

Update imports: Replace import jdk.incubator.concurrent.Something with appropriate standard imports.
Remove preview flags: Do not use --enable-preview on JDK 21 for virtual thread features.
Replace FiberScheduler: Use Executors.newVirtualThreadPerTaskExecutor() for custom scheduling needs.
Address thread pinning: Replace synchronized blocks with ReentrantLock when calling native code or performing blocking I/O.

Thread Pinning Considerations
JDK 21 enforces stricter thread pinning behavior. Virtual threads holding monitors (via synchronized) or executing native methods will block their carrier thread. To avoid performance issues:

Use java.util.concurrent.locks.ReentrantLock instead of synchronized for critical sections.
Minimize time spent in native code while holding locks.
Run with -Djdk.trace.threads to identify pinning hotspots during testing.

Questions for Further Diagnosis
If issues persist after migration, please provide:

The specific compilation or runtime error message you're encountering.
Whether your code uses custom schedulers or relies on synchronized blocks in I/O paths.

Virtual thread API migration failures from JDK 19/20 preview to JDK 21 final

1 answer

Confirmed API Changes in JDK 21

Migration Steps

Thread Pinning Considerations

Questions for Further Diagnosis

Your perspective belongs here.

0 question comments