Java Virtual Threads in Spring Boot Tutorial: Scaling to Millions of Requests

For years, scaling Java applications meant wrestling with thread pool sizes. If you had 200 concurrent requests hitting a blocking I/O endpoint, you needed 200 OS threads. In my experience, this is where most Spring Boot apps start to choke—not because of CPU limits, but because the memory overhead of platform threads becomes a bottleneck. This is why this java virtual threads in spring boot tutorial is so critical: Project Loom changes the fundamental math of concurrency.

Virtual threads are lightweight threads that aren’t tied 1:1 to OS threads. They allow you to write simple, synchronous-style code that performs like asynchronous, non-blocking code. If you’ve been optimizing Spring Boot startup time to squeeze more efficiency out of your pods, virtual threads are the next logical step in your performance journey.

Prerequisites

• JDK 21+: Virtual threads became production-ready in Java 21.
• Spring Boot 3.2+: This version introduced first-class support for virtual threads.
• IDE: IntelliJ IDEA (2023.2+) or VS Code with Java Extension Pack.
• Basic Knowledge: Familiarity with Spring MVC and REST controllers.

Step 1: Enabling Virtual Threads in Spring Boot

The beauty of Spring Boot 3.2 is that you no longer need to manually configure a VirtualThreadPerTaskExecutor. You can enable them with a single property in your application.properties or application.yml file.

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

By setting this to true, Spring Boot automatically configures the Tomcat server to use virtual threads for handling incoming HTTP requests. It also configures the TaskExecutor used for @Async methods to use virtual threads. I’ve found this to be the single most impactful configuration change for I/O-heavy applications.

Step 2: Implementing a High-Concurrency Endpoint

To see the difference, let’s create a service that simulates a blocking I/O call (like a slow API request or a legacy database query). In a traditional setup, this would quickly exhaust the Tomcat thread pool.

@RestController
@RequestMapping("/api/data")
public class DataController {

    @GetMapping("/slow")
    public String getSlowData() throws InterruptedException {
        // Simulate a blocking I/O operation
        Thread.sleep(Duration.ofSeconds(1)); 
        return "Data retrieved successfully!";
    }
}

When spring.threads.virtual.enabled is true, each call to /api/data/slow spawns a virtual thread. When Thread.sleep() is called, the virtual thread is “unmounted” from the carrier OS thread, allowing that OS thread to handle other requests while the virtual thread waits. As shown in the architecture diagram at the start of this post, this prevents the entire server from locking up.

Step 3: Using Virtual Threads with @Async

Beyond the web layer, you often need background processing. If you use the @Async annotation, Spring now leverages virtual threads automatically if the property is enabled.

@Service
public class NotificationService {

    @Async
    public void sendEmailNotification(String userEmail) {
        // This now runs on a virtual thread instead of a limited fixed pool
        log.info("Sending email to {} on thread {}", userEmail, Thread.currentThread());
        // Simulate network latency
        restTemplate.postForEntity("https://email-provider.com/send", request, String.class);
    }
}

If you are building an AI-integrated app—perhaps following a tutorial on Spring AI with OpenAI—virtual threads are a lifesaver. LLM responses are notoriously slow; using virtual threads ensures your application remains responsive while waiting for the AI to stream a response.

Pro Tips for Virtual Threads

• Avoid ThreadLocals: Virtual threads are designed to be created by the millions. Using heavy ThreadLocal variables can lead to massive memory consumption. Use ScopedValues (introduced as a preview feature) instead.
• Stop Pooling Threads: Never pool virtual threads. They are disposable. Creating a new one is nearly as cheap as creating a new object.
• Watch for Pinning: Be careful with synchronized blocks. If a virtual thread hits a synchronized block that performs I/O, it may “pin” the carrier thread, preventing other virtual threads from using it. Use ReentrantLock instead.

Troubleshooting Common Issues

If you notice that your application isn’t scaling as expected, check for Carrier Thread Pinning. You can diagnose this by adding the following JVM flag to your startup script:

-Djdk.tracePinnedThreads=full

This will print a stack trace to the console whenever a virtual thread pins its carrier thread, allowing you to identify the exact synchronized block causing the bottleneck.

What’s Next?

Now that you’ve mastered the basic java virtual threads in spring boot tutorial, I recommend looking into Structured Concurrency. This allows you to treat groups of related tasks as a single unit of work, making error handling and cancellation much simpler in highly concurrent environments.

Ready to push your app further? Check out my other guides on performance tuning and modern Java development to ensure your infrastructure can handle the throughput your code now allows.