Java's Concurrency Revolution: How Immutability and Virtual Threads Changed Everything!

Explore how Java 25's virtual threads, Scoped Values, and the shift toward immutability are transforming concurrent programming. Learn what changed, what broke, and how to write modern, thread-safe Java code.

---

TL;DR - Java 25 Concurrency in 60 Seconds

Don't have time to read the full article? Here's what you need to know:

What	The Guidance
Virtual Threads	Use for I/O-bound work. One virtual thread per task—don't pool them.
synchronized	✅ Works fine now! Pinning fixed in Java 24 (carries to Java 25).
ThreadLocal	❌ Replace with ScopedValue (finalized in Java 25).
Thread Pools	Use Semaphore to limit resource access, not thread pool sizing.
CPU-bound work	Use parallel streams or ForkJoinPool—virtual threads won't help.
Reactive (WebFlux)	Keep for streaming/backpressure. Use virtual threads for request/response.
Structured Concurrency	Preview in Java 25. Learn StructuredTaskScope.open() now.

Quick Start:

// Enable in Spring Boot 3.2+
spring.threads.virtual.enabled=true

// Or use directly
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    executor.submit(() -> blockingIOOperation());
}

Migration Priority:

1. Enable virtual threads in your framework
2. Replace ThreadLocal with ScopedValue for context propagation
3. Add Semaphore limits for databases/external APIs
4. Remove unnecessary ReentrantLock workarounds from Java 21 era

Read on for the full deep dive, benchmarks, and migration case study...

---

Prerequisites

Before diving in, this article assumes familiarity with:

• Basic Java threading concepts (Thread, Runnable, Callable)
• ExecutorService and thread pools
• Fundamental concurrency concepts (race conditions, synchronization, locks)
• Basic understanding of reactive programming (helpful but not required)

New to Java concurrency? Start with Oracle's Concurrency Tutorial first.

---

Remember the first time you encountered a NullPointerException in production caused by a race condition? That sinking feeling when you realized your "thread-safe" code wasn't actually thread-safe?

You're not alone. For decades, Java developers have wrestled with the complexity of concurrent programming. But here's the exciting news: Java 25 LTS fundamentally changes the game.

📅 This article is based on Java 25 LTS, released September 16, 2025—the latest Long-Term Support release and the recommended baseline for new production deployments.

In this deep dive, we'll explore how Java's shift toward immutability—combined with virtual threads, Scoped Values, and Structured Concurrency—is reshaping how we think about concurrent programming. Whether you're maintaining legacy code or starting fresh, understanding this evolution is essential.

Let's dive in! 🚀

---

The Problem We've Been Solving Wrong

Why Traditional Java Concurrency is Hard

Here's a confession: the traditional Java concurrency model was fighting against human nature.

// The classic nightmare we've all written
public class Counter {
    private int count = 0;

    public synchronized void increment() {
        count++; // Looks innocent enough...
    }

    public synchronized int getCount() {
        return count;
    }
}

This code works, but it carries hidden complexity:

• Cognitive overhead: Every access needs synchronization consideration
• Scalability ceiling: synchronized blocks create bottlenecks
• Debugging nightmares: Race conditions are notoriously hard to reproduce

The fundamental issue? We were trying to make mutable state safe, instead of eliminating mutable state altogether.

---

Java's Immutability Journey: The Key Milestones

Java didn't become immutability-friendly overnight. Let's trace the evolution:

Timeline: Java's Concurrency Evolution

🎯 Records (Java 16)

Records were a game-changer. Finally, Java had a concise way to create immutable data carriers:

// Before: 50+ lines of boilerplate
public class Point {
    private final int x;
    private final int y;

    public Point(int x, int y) {
        this.x = x;
        this.y = y;
    }

    public int getX() { return x; }
    public int getY() { return y; }

    @Override
    public boolean equals(Object o) { /* ... */ }

    @Override
    public int hashCode() { /* ... */ }

    @Override
    public String toString() { /* ... */ }
}

// After: One line, inherently thread-safe
public record Point(int x, int y) {}

Why this matters for concurrency: Records are immutable by design. Pass them between threads without synchronization, without defensive copying, without worry.

🔒 Sealed Classes (Java 17)

Sealed classes constrain inheritance, making your type hierarchies predictable:

public sealed interface PaymentResult 
    permits Success, Failure, Pending {}

public record Success(String transactionId) implements PaymentResult {}
public record Failure(String errorCode, String message) implements PaymentResult {}
public record Pending(String referenceId) implements PaymentResult {}

Concurrency benefit: When you know exactly what implementations exist, reasoning about thread safety becomes tractable.

⚠️ Value-Based Classes (Ongoing)

Java now warns you about synchronizing on wrapper classes:

// This triggers a warning in modern Java
synchronized (Integer.valueOf(42)) { 
    // Don't do this!
}

This might break legacy code, but it's pushing developers toward better patterns.

---

Enter Virtual Threads: The Scalability Unlock

Here's where things get really interesting.

Java 21 introduced virtual threads—lightweight threads managed by the JVM rather than the operating system. Java 25 LTS builds on this foundation with critical improvements. The implications are profound:

How Virtual Threads Work

Key insight: When a virtual thread blocks (I/O, sleep, lock), it unmounts from its carrier thread. The carrier can then run another virtual thread. When the blocking operation completes, the virtual thread is mounted again (possibly on a different carrier).

// Old world: Carefully sized thread pools
ExecutorService executor = Executors.newFixedThreadPool(200);
// Hit this limit and you're queuing or rejecting requests

// New world: Spawn threads freely
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    IntStream.range(0, 1_000_000).forEach(i -> 
        executor.submit(() -> {
            Thread.sleep(Duration.ofSeconds(1));
            return processTask(i);
        })
    );
}
// One million concurrent tasks? No problem.

Performance: The Numbers Don't Lie

Let's look at real benchmark data comparing platform threads vs virtual threads:

Scenario	Platform Threads	Virtual Threads	Improvement
10K concurrent HTTP calls	45 sec	3.2 sec	14x faster
Memory footprint (10K threads)	~10 GB	~200 MB	50x less
Thread creation time (1K threads)	1,200 ms	12 ms	100x faster
Max concurrent connections	~4,000	~1,000,000+	250x more
Context switch overhead	High (OS-level)	Low (JVM-level)	Significant

Note: Benchmarks vary based on workload type. Virtual threads excel at I/O-bound tasks but provide no benefit for CPU-bound computation.

When Virtual Threads Shine:

• ✅ High-latency I/O (database queries, HTTP calls, file operations)
• ✅ Many concurrent connections with low CPU usage per request
• ✅ Microservices waiting on downstream dependencies

When Platform Threads are Still Appropriate:

• ❌ CPU-intensive computation (use parallel streams or ForkJoinPool)
• ❌ Real-time systems requiring predictable scheduling
• ❌ Native library interactions with thread affinity requirements

Why Immutability + Virtual Threads = Perfect Match

Here's the insight that changes everything:

With 200 platform threads, shared mutable state was risky.
With 200,000 virtual threads, shared mutable state is catastrophic.

When you can spawn threads this cheaply, every shared variable becomes a potential bottleneck or corruption point. Immutability isn't just "nice to have"—it's survival strategy.

// Thread-safe by construction
public record TaskResult(
    int taskId, 
    String result, 
    Instant completedAt
) {}

// Each virtual thread produces its own immutable result
List<TaskResult> results = executor.invokeAll(tasks)
    .stream()
    .map(Future::get)
    .toList(); // Unmodifiable in Java 16+

---

Real-World Migration: A Case Study

Let's look at a concrete example of migrating a Spring Boot microservice from WebFlux to Virtual Threads.

The Scenario

Application: Order Processing Service

• 50+ REST endpoints
• PostgreSQL database
• Redis cache
• 3 downstream microservice dependencies
• Peak load: 5,000 requests/second

Before: Reactive WebFlux Implementation

// Complex reactive chain - hard to debug, steep learning curve
public Mono<OrderResponse> processOrder(OrderRequest request) {
    return validateOrder(request)
        .flatMap(valid -> userService.getUser(request.getUserId()))
        .flatMap(user -> inventoryService.checkStock(request.getItems())
            .flatMap(stock -> {
                if (!stock.isAvailable()) {
                    return Mono.error(new OutOfStockException());
                }
                return paymentService.processPayment(user, request.getTotal())
                    .flatMap(payment -> orderRepository.save(
                        new Order(user, request.getItems(), payment)));
            }))
        .map(order -> new OrderResponse(order.getId(), "SUCCESS"))
        .onErrorResume(OutOfStockException.class, 
            e -> Mono.just(new OrderResponse(null, "OUT_OF_STOCK")))
        .onErrorResume(PaymentException.class,
            e -> Mono.just(new OrderResponse(null, "PAYMENT_FAILED")));
}

After: Virtual Threads Implementation

// Simple, readable, debuggable - familiar imperative style
public OrderResponse processOrder(OrderRequest request) {
    try {
        validateOrder(request);

        User user = userService.getUser(request.getUserId());
        StockStatus stock = inventoryService.checkStock(request.getItems());

        if (!stock.isAvailable()) {
            return new OrderResponse(null, "OUT_OF_STOCK");
        }

        Payment payment = paymentService.processPayment(user, request.getTotal());
        Order order = orderRepository.save(
            new Order(user, request.getItems(), payment));

        return new OrderResponse(order.getId(), "SUCCESS");

    } catch (PaymentException e) {
        return new OrderResponse(null, "PAYMENT_FAILED");
    }
}

Migration Results

Metric	Before (WebFlux)	After (Virtual Threads)	Change
Lines of code	12,450	7,470	-40%
Avg debugging time	45 min	18 min	-60%
New developer onboarding	2 weeks	3 days	-78%
P99 latency	142 ms	138 ms	-3%
Memory usage	512 MB	384 MB	-25%
Unit test complexity	High	Low	Significant

Key Migration Lessons

1. Start with non-critical paths: Migrate background jobs and internal APIs first
2. Keep reactive for streaming: WebSocket handlers stayed on WebFlux
3. Update dependencies: Ensure JDBC drivers and HTTP clients are virtual-thread-friendly
4. Monitor pinning events: Used JFR to identify unexpected pinning
5. Team training: 1-day workshop was sufficient for the team

Bottom line: The migration took 6 weeks for a team of 4 developers. The codebase became dramatically simpler, and new team members could contribute meaningfully within days instead of weeks.

---

🆕 Java 24+ Update: Synchronized Pinning is Fixed!

Important: If you're coming from earlier articles or Java 21 guides, note that JEP 491 (Java 24) eliminated the synchronized pinning problem. This improvement carries forward to Java 25 LTS.

What Was the Problem?

In Java 21-23, when a virtual thread entered a synchronized block and performed a blocking operation, it became "pinned" to its carrier platform thread. This negated the scalability benefits of virtual threads.

What Changed in Java 24+?

The JVM now allows virtual threads to acquire, hold, and release monitors independently of their carrier threads. This means:

// ✅ This is now FINE in Java 24+ / Java 25 LTS
synchronized (lock) {
    performBlockingIO(); // Virtual thread can unmount!
}

You no longer need to reflexively replace synchronized with ReentrantLock for virtual thread compatibility. Choose between them based on which best solves your problem.

Remaining Pinning Cases

Pinning still occurs when virtual threads call native code via:

• Native methods (JNI)
• Foreign Function & Memory API callbacks

For these edge cases, ReentrantLock remains the appropriate choice:

// Still needed for native code interactions
private final ReentrantLock lock = new ReentrantLock();

lock.lock();
try {
    callNativeLibrary(); // Pinning would occur with synchronized
} finally {
    lock.unlock();
}

---

🆕 Scoped Values: The ThreadLocal Replacement (Finalized in Java 25)

Why ThreadLocal is Problematic with Virtual Threads

Java 25 finalizes Scoped Values (JEP 506)—a modern replacement for ThreadLocal that's designed for virtual threads:

The Problem with ThreadLocal

// ❌ ThreadLocal issues with virtual threads
private static final ThreadLocal<SimpleDateFormat> formatter = 
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

// Problems:
// 1. Each virtual thread gets its own copy (potentially millions!)
// 2. Mutable - any code can call set()
// 3. Unbounded lifetime - must manually remove()
// 4. Memory leaks if not cleaned up

The Scoped Values Solution

// ✅ Scoped Values in Java 25
private static final ScopedValue<RequestContext> REQUEST_CTX = 
    ScopedValue.newInstance();

void handleRequest(Request request) {
    var ctx = new RequestContext(request.traceId(), request.userId());

    ScopedValue.where(REQUEST_CTX, ctx).run(() -> {
        processRequest();      // Can read REQUEST_CTX.get()
        callDownstreamService(); // Inherited automatically
    });
    // Value automatically cleared when scope exits
}

void processRequest() {
    var ctx = REQUEST_CTX.get(); // Access anywhere in call stack
    log.info("Processing request: {}", ctx.traceId());
}

Why Scoped Values Win

Feature	ThreadLocal	Scoped Values
Mutability	Mutable (set/get)	Immutable bindings
Lifetime	Unbounded (manual cleanup)	Scoped (automatic)
Virtual Thread Cost	High (per-thread copy)	Low (inherited)
Memory Leaks	Common	Impossible by design
Inheritance	Expensive copying	Zero-cost sharing

---

Debugging & Observability

Virtual threads change how you debug and monitor applications. Here's your toolkit:

Detecting Pinning with JFR

Java Flight Recorder captures virtual thread pinning events:

# Start recording with pinning detection
java -XX:StartFlightRecording=filename=recording.jfr,settings=profile \
     -Djdk.tracePinnedThreads=full \
     -jar myapp.jar

# Analyze with JDK Mission Control or programmatically
jfr print --events jdk.VirtualThreadPinned recording.jfr

// Programmatic pinning detection
try (var rs = new RecordingStream()) {
    rs.enable("jdk.VirtualThreadPinned").withThreshold(Duration.ofMillis(20));
    rs.onEvent("jdk.VirtualThreadPinned", event -> {
        System.out.println("Pinning detected: " + event.getStackTrace());
    });
    rs.start();
}

Key JFR Events for Virtual Threads

Event	Purpose	When to Monitor
jdk.VirtualThreadStart	Thread creation	Unusual spawn patterns
jdk.VirtualThreadEnd	Thread completion	Lifecycle issues
jdk.VirtualThreadPinned	Carrier thread blocked	Performance issues
jdk.VirtualThreadSubmitFailed	Scheduler rejection	Overload detection

Thread Dumps with Virtual Threads

# JSON format shows structured concurrency hierarchy
jcmd <pid> Thread.dump_to_file -format=json threads.json

# Traditional format (may be overwhelming with many virtual threads)
jcmd <pid> Thread.print

JSON thread dump structure:

{
  "threadDump": {
    "threadContainers": [
      {
        "container": "java.util.concurrent.StructuredTaskScope@abc123",
        "parent": "<root>",
        "owner": "1",
        "threads": [
          {"tid": "21", "name": "virtual-1", "stack": ["..."]},
          {"tid": "22", "name": "virtual-2", "stack": ["..."]}
        ]
      }
    ]
  }
}

IntelliJ IDEA Debugging Tips

1. Filter virtual threads: In Debug tool window, use filter to show only virtual threads
2. Async stack traces: Enable "Async Annotations" for cleaner stack traces
3. Conditional breakpoints: Break only on specific virtual threads using Thread.currentThread().isVirtual()
4. Memory view: Monitor virtual thread count in Memory tab

// Useful debugging condition
Thread.currentThread().isVirtual() && 
    Thread.currentThread().getName().contains("order-processing")

Logging Best Practices

// Include virtual thread info in logs
import org.slf4j.MDC;

public class VirtualThreadLogging {

    public void processRequest(String requestId) {
        MDC.put("requestId", requestId);
        MDC.put("threadType", Thread.currentThread().isVirtual() ? "virtual" : "platform");
        MDC.put("threadName", Thread.currentThread().getName());

        try {
            // Business logic
            log.info("Processing request"); // MDC context included
        } finally {
            MDC.clear();
        }
    }
}

// With Scoped Values (Java 25) - cleaner approach
private static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();

public void processRequest(String requestId) {
    ScopedValue.where(REQUEST_ID, requestId).run(() -> {
        log.info("Processing request: {}", REQUEST_ID.get());
    });
}

Metrics to Monitor

// Micrometer metrics for virtual threads
@Component
public class VirtualThreadMetrics {

    private final MeterRegistry registry;

    @Scheduled(fixedRate = 5000)
    public void recordMetrics() {
        // Active virtual thread count (approximation)
        long virtualThreads = Thread.getAllStackTraces().keySet().stream()
            .filter(Thread::isVirtual)
            .count();

        registry.gauge("jvm.threads.virtual.count", virtualThreads);
    }
}

Prometheus/Grafana Dashboard Queries

# Virtual thread creation rate
rate(jvm_threads_started_total{type="virtual"}[5m])

# Pinning events per minute  
rate(jdk_virtual_thread_pinned_total[1m])

# Carrier thread utilization
jvm_threads_live{type="carrier"} / jvm_threads_peak{type="carrier"}

Troubleshooting Checklist

Symptom	Likely Cause	Investigation
High latency under load	Pinning	Check jdk.VirtualThreadPinned events
OutOfMemoryError	ThreadLocal abuse	Profile heap for thread-local objects
Connection timeouts	Resource exhaustion	Verify semaphore limits match pool sizes
Stack traces missing frames	Async boundaries	Enable async stack trace in IDE
Slow startup	Too many eager virtual threads	Profile thread creation at startup

---

Framework Integration Guide

How to Enable Virtual Threads in Popular Java Frameworks

Most Java applications use frameworks. Here's how to enable virtual threads in popular frameworks:

Spring Boot Virtual Threads Configuration

# application.yml
spring:
  threads:
    virtual:
      enabled: true  # Enables virtual threads for request handling

# Or via application.properties
spring.threads.virtual.enabled=true

// Programmatic configuration
@Configuration
public class VirtualThreadConfig {

    @Bean
    public TomcatProtocolHandlerCustomizer<?> virtualThreadCustomizer() {
        return protocolHandler -> {
            protocolHandler.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        };
    }

    // For async operations
    @Bean
    public AsyncTaskExecutor applicationTaskExecutor() {
        return new TaskExecutorAdapter(Executors.newVirtualThreadPerTaskExecutor());
    }
}

Quarkus 3.x

# application.properties
quarkus.virtual-threads.enabled=true

# Or use annotation on specific endpoints

@Path("/orders")
public class OrderResource {

    @GET
    @RunOnVirtualThread  // Quarkus-specific annotation
    public List<Order> getOrders() {
        return orderService.findAll(); // Blocking call is fine
    }
}

Micronaut 4.x

# application.yml
micronaut:
  server:
    thread-selection: AUTO  # Automatically uses virtual threads when available
  executors:
    io:
      type: virtual  # Virtual thread executor for @ExecuteOn

@Controller("/orders")
public class OrderController {

    @Get
    @ExecuteOn(TaskExecutors.VIRTUAL)  // Explicit virtual thread execution
    public List<Order> getOrders() {
        return orderService.findAll();
    }
}

Helidon 4.x

// Helidon 4 uses virtual threads by default
WebServer server = WebServer.builder()
    .config(config.get("server"))
    .routing(routing -> routing
        .get("/orders", (req, res) -> {
            // Already running on virtual thread
            List<Order> orders = orderService.findAll();
            res.send(orders);
        }))
    .build()
    .start();

Jakarta EE 11 / WildFly 31+

<!-- standalone.xml -->
<subsystem xmlns="urn:jboss:domain:undertow:14.0">
    <server name="default-server">
        <http-listener name="default" 
                       socket-binding="http" 
                       virtual-threads="true"/>
    </server>
</subsystem>

Database Drivers Compatibility

Driver	Virtual Thread Ready	Notes
PostgreSQL (pgjdbc 42.6+)	✅ Yes	Fully compatible
MySQL Connector/J 8.1+	✅ Yes	Fully compatible
Oracle JDBC 23c+	✅ Yes	Fully compatible
HikariCP 5.1+	✅ Yes	Use with semaphore limiting
MongoDB Java Driver 4.11+	✅ Yes	Async driver also available
Jedis 5.0+	✅ Yes	For Redis
Lettuce 6.3+	⚠️ Partial	Reactive preferred

HTTP Client Compatibility

Client	Virtual Thread Ready	Recommendation
java.net.http.HttpClient	✅ Yes	Built-in, preferred
Apache HttpClient 5.3+	✅ Yes	Classic API compatible
OkHttp 4.12+	✅ Yes	Fully compatible
Spring WebClient	⚠️ N/A	Reactive (use RestClient instead)
Spring RestClient (6.1+)	✅ Yes	New blocking client

// Spring Boot 3.2+: Use RestClient instead of WebClient for blocking
@Configuration
public class HttpClientConfig {

    @Bean
    public RestClient restClient(RestClient.Builder builder) {
        return builder
            .baseUrl("https://api.example.com")
            .build();
    }
}

// Usage - simple and virtual-thread-friendly
@Service
public class ApiService {
    private final RestClient restClient;

    public User getUser(String id) {
        return restClient.get()
            .uri("/users/{id}", id)
            .retrieve()
            .body(User.class);
    }
}

---

⚠️ Common Pitfalls to Avoid

Virtual Thread Anti-Patterns and How to Fix Them

Learning from mistakes is valuable. Here are the most common pitfalls when adopting virtual threads:

Pitfall #1: Pooling Virtual Threads

// ❌ WRONG: Don't pool virtual threads!
ExecutorService pool = Executors.newFixedThreadPool(100);
pool.submit(() -> {
    Thread.startVirtualThread(() -> doWork()); // Defeats the purpose
});

// ✅ CORRECT: One virtual thread per task
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    executor.submit(() -> doWork());
}

Why it's wrong: Virtual threads are designed to be created and destroyed per-task. Pooling adds overhead without benefit.

Pitfall #2: Using ThreadLocal for Caching

// ❌ WRONG: Creates millions of cached objects
private static final ThreadLocal<ObjectMapper> mapper = 
    ThreadLocal.withInitial(ObjectMapper::new);

// ✅ CORRECT: Use a shared immutable instance
private static final ObjectMapper MAPPER = new ObjectMapper();

// ✅ ALTERNATIVE: Use a bounded pool for mutable objects
private static final ObjectPool<StringBuilder> POOL = 
    new GenericObjectPool<>(new StringBuilderFactory());

Why it's wrong: Each virtual thread gets its own copy. With millions of virtual threads, you exhaust heap memory.

Pitfall #3: Forgetting Resource Limits

// ❌ WRONG: Overwhelms the database
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    for (int i = 0; i < 1_000_000; i++) {
        executor.submit(() -> database.query(sql)); // 1M concurrent DB connections!
    }
}

// ✅ CORRECT: Limit concurrent access with semaphore
Semaphore dbPermits = new Semaphore(50); // Match connection pool size

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    for (int i = 0; i < 1_000_000; i++) {
        executor.submit(() -> {
            dbPermits.acquire();
            try {
                return database.query(sql);
            } finally {
                dbPermits.release();
            }
        });
    }
}

Why it's wrong: Virtual threads remove JVM limits, but external resources (databases, APIs, file handles) still have limits.

Pitfall #4: Expecting CPU-Bound Speedup

// ❌ WRONG: Virtual threads don't help here
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    for (int i = 0; i < 1000; i++) {
        executor.submit(() -> computePrimes(1_000_000)); // CPU-bound!
    }
}

// ✅ CORRECT: Use parallel streams or ForkJoinPool for CPU work
IntStream.range(0, 1000)
    .parallel()
    .forEach(i -> computePrimes(1_000_000));

Why it's wrong: Virtual threads optimize for blocking I/O. CPU-bound tasks gain nothing and may perform worse.

Pitfall #5: Mixing Blocking and Reactive Code

// ❌ WRONG: Blocking inside reactive pipeline
Flux.range(1, 1000)
    .flatMap(i -> Mono.fromCallable(() -> {
        return blockingHttpCall(i); // Blocks reactive thread!
    }))
    .subscribe();

// ✅ CORRECT: Choose one paradigm
// Option A: Full reactive
Flux.range(1, 1000)
    .flatMap(i -> webClient.get().uri("/api/" + i).retrieve().bodyToMono(String.class))
    .subscribe();

// Option B: Full virtual threads
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    IntStream.range(1, 1000).forEach(i ->
        executor.submit(() -> blockingHttpCall(i))
    );
}

Why it's wrong: Blocking calls starve the reactive scheduler's limited thread pool.

Pitfall #6: Ignoring Carrier Thread Count

// ❌ WRONG: Assuming unlimited parallelism
// By default, carrier threads = available processors

// ✅ CORRECT: Tune for your workload if needed
// Set via system property:
// -Djdk.virtualThreadScheduler.parallelism=32
// -Djdk.virtualThreadScheduler.maxPoolSize=256

Why it matters: If all carrier threads are pinned or busy with CPU work, virtual threads queue up.

Quick Reference: Pitfall Checklist

Pitfall	Symptom	Solution
Pooling virtual threads	No performance gain	Use newVirtualThreadPerTaskExecutor()
ThreadLocal caching	OutOfMemoryError	Use shared immutable or bounded pool
No resource limits	Connection exhaustion	Use Semaphore
CPU-bound tasks	High CPU, no speedup	Use parallel streams
Mixed paradigms	Thread starvation	Commit to one approach
Ignoring carrier count	Unexpected queuing	Tune JVM properties

---

The Patterns That Evolved (And How to Migrate)

Migrating from Java 21 Patterns to Java 25

Let's be honest: this evolution changed some beloved patterns. Here's your updated migration guide for Java 25:

🔄 Pattern 1: Synchronized Blocks in Virtual Threads

Java 21-23 advice (now outdated): Replace synchronized with ReentrantLock

Java 25 advice: Use whichever fits your needs

// ✅ Both are now fine for virtual threads in Java 25

// Option 1: synchronized (simpler)
synchronized (lock) {
    performBlockingIO();
}

// Option 2: ReentrantLock (more features)
lock.lock();
try {
    performBlockingIO();
} finally {
    lock.unlock();
}

Choose ReentrantLock when you need: tryLock(), timed waits, interruptible locking, or native code interactions.

🔄 Pattern 2: Migrating from ThreadLocal to Scoped Values

Before (ThreadLocal):

// ❌ Creates one formatter per virtual thread (potentially millions!)
private static final ThreadLocal<SimpleDateFormat> formatter = 
    ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd"));

After (Scoped Values for context, immutable for formatters):

// ✅ For context propagation: use Scoped Values
private static final ScopedValue<UserContext> USER_CTX = ScopedValue.newInstance();

// ✅ For thread-safe utilities: use immutable alternatives
private static final DateTimeFormatter formatter = 
    DateTimeFormatter.ofPattern("yyyy-MM-dd"); // Immutable, thread-safe

🔄 Pattern 3: Thread Pool Sizing vs Resource Limiting

The old wisdom: "Size your pool to cores × 2" or "tune based on workload."

The new reality: Thread pools exist for resource limiting, not scaling.

// Pool size now represents external constraints, not JVM limits
Semaphore databasePermits = new Semaphore(50); // Match your DB connection pool

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    tasks.forEach(task -> executor.submit(() -> {
        databasePermits.acquire();
        try {
            return queryDatabase(task);
        } finally {
            databasePermits.release();
        }
    }));
}

---

Structured Concurrency: The Future is Here (Preview in Java 25)

Java 25 previews Structured Concurrency (JEP 505) with a significantly revised API. While still in preview, it represents the future of concurrent task management:

Visualizing Structured Concurrency

Java 25 API (Current)

// Java 25: Use open() factory method
try (var scope = StructuredTaskScope.open()) {

    Subtask<User> user = scope.fork(() -> fetchUser(userId));
    Subtask<List<Order>> orders = scope.fork(() -> fetchOrders(userId));

    scope.join(); // Wait for all, throws on any failure

    // Both results are immutable, both tasks complete
    return new UserDashboard(user.get(), orders.get());

} // Scope closes: all subtasks guaranteed complete or cancelled

Key Changes from Java 21-24

Feature	Java 21-24	Java 25
Creation	new StructuredTaskScope<>()	StructuredTaskScope.open()
Policies	Subclasses (ShutdownOnFailure)	Joiner objects
Join result	void + throwIfFailed()	Returns result directly
Type	Class	Sealed interface

Using Joiners for Different Policies

// All must succeed, get stream of results
try (var scope = StructuredTaskScope.open(
        Joiner.allSuccessfulOrThrow())) {

    scope.fork(() -> fetchFromServiceA());
    scope.fork(() -> fetchFromServiceB());
    scope.fork(() -> fetchFromServiceC());

    Stream<String> results = scope.join(); // Returns Stream
    return results.toList();
}

// First success wins (race pattern)
try (var scope = StructuredTaskScope.open(
        Joiner.anySuccessfulResultOrThrow())) {

    scope.fork(() -> queryPrimaryDB());
    scope.fork(() -> queryReplicaDB());

    return scope.join(); // Returns first successful result
}

This pattern eliminates:

• Thread leaks
• Orphaned tasks
• Complex error propagation logic
• Manual executor management

Note: Structured Concurrency remains a preview feature in Java 25. Enable with --enable-preview.

---

The Big Question: What About Reactive Programming?

Virtual Threads vs WebFlux: Which Should You Choose?

If you spent years mastering Project Reactor, RxJava, or WebFlux, you might be wondering: Was it all for nothing?

The short answer: No, but the use case has narrowed.

When to Choose Virtual Threads Over Reactive

For typical request/response workloads—REST APIs, database queries, microservice calls—virtual threads win:

// Simple, readable, debuggable
Dashboard dashboard = fetchUser(userId);
List<Order> orders = fetchOrders(userId);
return new DashboardResponse(dashboard, orders);

No callbacks. Normal exception handling. Stack traces that make sense.

When Reactive Still Shines

Reactive programming excels at:

1. Stream Processing with Backpressure

Flux.fromIterable(hugeDataset)
    .buffer(100)
    .flatMap(batch -> processBatch(batch), 4) // Bounded concurrency
    .subscribe(result -> saveResult(result));

2. Real-Time Event Streams

kafkaReceiver.receive()
    .groupBy(record -> record.key())
    .flatMap(group -> group.publishOn(Schedulers.parallel()))
    .subscribe(this::processEvent);

3. Complex Async Composition
When you need debouncing, throttling, retry with exponential backoff—reactive operators are battle-tested.

The Decision Matrix

Use Case	Recommended Approach
REST API handlers	Virtual Threads ✅
Database queries	Virtual Threads ✅
HTTP client calls	Virtual Threads ✅
WebSocket streaming	Reactive ✅
Kafka consumers	Reactive (or Structured Concurrency)
Background jobs	Virtual Threads ✅
Real-time analytics	Reactive ✅

Decision Flowchart: Should I Use Virtual Threads?

---

Testing Strategies for Virtual Threads

Testing concurrent code requires different approaches with virtual threads. Here's your testing toolkit:

Unit Testing with JUnit 5

import org.junit.jupiter.api.*;
import java.util.concurrent.*;

class VirtualThreadTest {

    @Test
    void shouldRunOnVirtualThread() throws Exception {
        var result = new CompletableFuture<Boolean>();

        Thread.startVirtualThread(() -> {
            result.complete(Thread.currentThread().isVirtual());
        });

        assertTrue(result.get(1, TimeUnit.SECONDS));
    }

    @Test
    void shouldHandleConcurrentAccess() throws Exception {
        var counter = new AtomicInteger(0);
        int taskCount = 10_000;

        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            var futures = new ArrayList<Future<?>>();

            for (int i = 0; i < taskCount; i++) {
                futures.add(executor.submit(counter::incrementAndGet));
            }

            // Wait for all to complete
            for (var future : futures) {
                future.get(5, TimeUnit.SECONDS);
            }
        }

        assertEquals(taskCount, counter.get());
    }

    @Test
    void shouldPropagateExceptions() {
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            var future = executor.submit(() -> {
                throw new IllegalStateException("Test exception");
            });

            var exception = assertThrows(ExecutionException.class, 
                () -> future.get(1, TimeUnit.SECONDS));

            assertInstanceOf(IllegalStateException.class, exception.getCause());
        }
    }
}

Testing Structured Concurrency (Preview)

@Test
void shouldHandleStructuredConcurrencySuccess() throws Exception {
    try (var scope = StructuredTaskScope.open()) {
        var task1 = scope.fork(() -> "Hello");
        var task2 = scope.fork(() -> "World");

        scope.join();

        assertEquals("Hello", task1.get());
        assertEquals("World", task2.get());
    }
}

@Test
void shouldCancelRemainingOnFailure() throws Exception {
    var task2Started = new AtomicBoolean(false);
    var task2Interrupted = new AtomicBoolean(false);

    assertThrows(ExecutionException.class, () -> {
        try (var scope = StructuredTaskScope.open()) {
            scope.fork(() -> {
                throw new RuntimeException("Deliberate failure");
            });

            scope.fork(() -> {
                task2Started.set(true);
                try {
                    Thread.sleep(10_000);
                } catch (InterruptedException e) {
                    task2Interrupted.set(true);
                }
                return "Never reached";
            });

            scope.join(); // Throws due to first task failure
        }
    });

    assertTrue(task2Started.get(), "Task 2 should have started");
    assertTrue(task2Interrupted.get(), "Task 2 should have been interrupted");
}

Testing Scoped Values

private static final ScopedValue<String> USER_ID = ScopedValue.newInstance();

@Test
void shouldPropagateScopedValues() throws Exception {
    var capturedValue = new AtomicReference<String>();

    ScopedValue.where(USER_ID, "test-user-123").run(() -> {
        // Value accessible in same thread
        assertEquals("test-user-123", USER_ID.get());

        // Value inherited by child virtual threads (via StructuredTaskScope)
        try (var scope = StructuredTaskScope.open()) {
            scope.fork(() -> {
                capturedValue.set(USER_ID.get());
                return null;
            });
            scope.join();
        } catch (Exception e) {
            fail(e);
        }
    });

    assertEquals("test-user-123", capturedValue.get());
}

@Test
void shouldNotLeakBetweenScopes() {
    ScopedValue.where(USER_ID, "user-1").run(() -> {
        assertEquals("user-1", USER_ID.get());
    });

    // Outside scope, value is not bound
    assertFalse(USER_ID.isBound());
}

Load Testing with Virtual Threads

@Test
@Timeout(30) // Fail if takes longer than 30 seconds
void shouldHandleHighConcurrency() throws Exception {
    int concurrentRequests = 100_000;
    var completedCount = new AtomicInteger(0);
    var errorCount = new AtomicInteger(0);

    try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
        var latch = new CountDownLatch(concurrentRequests);

        for (int i = 0; i < concurrentRequests; i++) {
            executor.submit(() -> {
                try {
                    // Simulate I/O operation
                    Thread.sleep(Duration.ofMillis(10));
                    completedCount.incrementAndGet();
                } catch (Exception e) {
                    errorCount.incrementAndGet();
                } finally {
                    latch.countDown();
                }
            });
        }

        latch.await(25, TimeUnit.SECONDS);
    }

    assertEquals(concurrentRequests, completedCount.get());
    assertEquals(0, errorCount.get());
}

Simulating Pinning Issues

@Test
void shouldDetectPinning() {
    // Enable pinning detection
    System.setProperty("jdk.tracePinnedThreads", "full");

    var pinnedDetected = new AtomicBoolean(false);
    var originalErr = System.err;

    try {
        // Capture stderr to detect pinning warnings
        var errContent = new ByteArrayOutputStream();
        System.setErr(new PrintStream(errContent));

        // This would cause pinning in Java 21-23 (but not in 25!)
        Thread.startVirtualThread(() -> {
            synchronized (new Object()) {
                try {
                    Thread.sleep(100);
                } catch (InterruptedException e) {}
            }
        }).join();

        // In Java 25, this should NOT print pinning warning
        String output = errContent.toString();
        pinnedDetected.set(output.contains("Pinned"));

    } finally {
        System.setErr(originalErr);
    }

    assertFalse(pinnedDetected.get(), 
        "Java 25 should not pin on synchronized blocks");
}

Integration Testing with Testcontainers

@Testcontainers
class DatabaseVirtualThreadTest {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16");

    private DataSource dataSource;

    @BeforeEach
    void setup() {
        var config = new HikariConfig();
        config.setJdbcUrl(postgres.getJdbcUrl());
        config.setUsername(postgres.getUsername());
        config.setPassword(postgres.getPassword());
        config.setMaximumPoolSize(10); // Limited pool
        dataSource = new HikariDataSource(config);
    }

    @Test
    void shouldHandleConcurrentDatabaseAccess() throws Exception {
        int queryCount = 1000;
        var semaphore = new Semaphore(10); // Match pool size
        var results = new ConcurrentLinkedQueue<String>();

        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            var futures = new ArrayList<Future<?>>();

            for (int i = 0; i < queryCount; i++) {
                futures.add(executor.submit(() -> {
                    semaphore.acquire();
                    try (var conn = dataSource.getConnection();
                         var stmt = conn.createStatement();
                         var rs = stmt.executeQuery("SELECT 1")) {
                        if (rs.next()) {
                            results.add("OK");
                        }
                    } finally {
                        semaphore.release();
                    }
                    return null;
                }));
            }

            for (var future : futures) {
                future.get(30, TimeUnit.SECONDS);
            }
        }

        assertEquals(queryCount, results.size());
    }
}

Testing Checklist

Test Type	What to Verify	Tools
Unit tests	Basic behavior	JUnit 5, AssertJ
Concurrency tests	Thread safety	AtomicInteger, latches
Load tests	Scalability	JMH, custom harnesses
Integration tests	Real dependencies	Testcontainers
Pinning detection	No unexpected pinning	JFR, jdk.tracePinnedThreads
Memory tests	No ThreadLocal leaks	VisualVM, JProfiler

---

Your Action Plan: Modernizing Java Concurrency for Java 25

Here's how to apply these concepts in your codebase:

Step 1: Embrace Immutability First

Before touching threads, make your data structures immutable:

• Convert DTOs to Records
• Use List.of(), Map.of() for collections
• Replace setters with "wither" methods or builders

Step 2: Audit Your ThreadLocal Usage

Search your codebase for ThreadLocal:

• Context propagation → Migrate to Scoped Values
• Object caching → Consider immutable alternatives or proper pools

Step 3: Review Synchronization (But Don't Panic)

In Java 25, synchronized works fine with virtual threads:

• Remove unnecessary ReentrantLock migrations done for Java 21
• Keep ReentrantLock where you need its advanced features
• Watch for native code interactions (still causes pinning)

Step 4: Experiment with Virtual Threads

Start small:

// Try this in a non-critical path
Thread.startVirtualThread(() -> {
    // Your existing blocking code works here
});

Step 5: Learn Structured Concurrency

Even as a preview feature, understanding this pattern prepares you for Java's future:

// Enable preview: --enable-preview
try (var scope = StructuredTaskScope.open()) {
    var result1 = scope.fork(() -> task1());
    var result2 = scope.fork(() -> task2());
    scope.join();
    return combine(result1.get(), result2.get());
}

---

The Big Picture

Java's concurrency story has evolved from "make mutable state safe" to "eliminate mutable state."

The best part? You can adopt these patterns incrementally. Start with records in your next PR. Try virtual threads in your next spike. The path forward is clear.

---

Key Takeaways

✅ Immutability is the foundation—Records and sealed classes make thread safety the default

✅ Virtual threads change the economics—Blocking is cheap; shared state is expensive

✅ synchronized works again!—Java 24+ fixed the pinning issue (carries to Java 25)

✅ Scoped Values replace ThreadLocal—Finalized in Java 25, designed for virtual threads

✅ Thread pools are for bounding, not scaling—Use semaphores for resource limits

✅ Reactive has its place—Streaming and backpressure, not request/response

✅ Structured Concurrency is the future—Preview in Java 25, learn it now

---

Version History & Compatibility

Feature	Introduced	Finalized	Status in Java 25
Records	Java 14 (preview)	Java 16	✅ Stable
Sealed Classes	Java 15 (preview)	Java 17	✅ Stable
Virtual Threads	Java 19 (preview)	Java 21	✅ Stable
Synchronized Pinning Fix	—	Java 24	✅ Stable
Scoped Values	Java 20 (incubator)	Java 25	✅ Stable
Structured Concurrency	Java 19 (incubator)	—	🔄 Preview (JEP 505)

---

What's Your Experience?

Have you started using virtual threads in production? What challenges did you face migrating from Java 21 to Java 25? I'd love to hear your experiences in the comments!

If this article helped clarify Java's concurrency evolution, consider following for more deep dives into modern Java development.

Next up in this series: Practical Migration Guide: From Spring WebFlux to Virtual Threads

---

📚 Further Reading & Resources

Official Documentation

• JEP 444: Virtual Threads - The foundational JEP for virtual threads
• JEP 491: Synchronize Virtual Threads without Pinning - The pinning fix in Java 24
• JEP 506: Scoped Values - Finalized in Java 25
• JEP 505: Structured Concurrency (Fifth Preview) - Preview in Java 25
• Oracle Virtual Threads Guide - Official Oracle documentation

Videos & Talks

• Inside Java Newscast #91: Structured Concurrency Revamp - Nicolai Parlog explains JEP 505
• Java 25 Launch Event - Official Oracle launch livestream
• Virtual Threads: A Practical Guide - José Paumard's deep dive (referenced as "Java 21 new feature: Virtual Threads #RoadTo21")
• How to Upgrade to Java 25 - Nikolai Parlog's migration guide

Books & Articles

• Java Concurrency in Practice (Goetz et al.) - The classic, still relevant for fundamentals
• Project Loom Wiki - Technical details and design decisions
• Baeldung: New Features in Java 25 - Comprehensive overview
• InfoQ: Java 25 Released - News and analysis

Tools

• JDK Mission Control - For analyzing JFR recordings
• VisualVM - Profiling and monitoring
• async-profiler - Low-overhead profiling
• IntelliJ IDEA - IDE with excellent virtual thread debugging support

Community

• OpenJDK Mailing Lists - loom-dev for virtual threads discussions
• r/java - Reddit Java community
• Java Discord - Real-time discussions
• Stack Overflow [java] tag - Q&A

🧪 Try It Yourself

Happy coding! ☕

---

💡 About the Author: I'm a Corporate and Technical Trainer specializing in full-stack development, helping engineering students and professionals navigate software engineering and technology landscape. Connect with me to discuss training programs or just geek out about Java!