Enable Java Virtual Threads in Spring Boot for Million‑Scale Concurrency

What are virtual threads?

Virtual threads are lightweight Java threads introduced in JDK 19 and fully supported in JDK 21. Unlike platform (OS) threads, they are scheduled by the JVM in user space, allowing each thread to block without occupying an OS thread. This M:N scheduling model reduces the memory footprint of a thread from ~1 MB to a few kilobytes and enables thousands‑to‑millions of concurrent tasks, especially for I/O‑bound or blocking workloads, while preserving the familiar synchronous programming model.

普通线程（平台线程，1:1）
+----------------------------+
|  OS Thread 1               |
|  ┌───────────────┐        |
|  | Task A (阻塞)  |        |
|  └───────────────┘        |
+----------------------------+
+----------------------------+
|  OS Thread 2               |
|  ┌───────────────┐        |
|  | Task B        |        |
|  └───────────────┘        |
+----------------------------+
每个任务占用一个 OS 线程，阻塞浪费资源，线程数量受限，内存消耗大

虚拟线程（Virtual Thread，M:N）
+------------------------------------------------------+
|  Platform Thread 1                                 |
|  ┌───────────┐ ┌───────────┐ ┌───────────┐        |
|  | VThread A | | VThread B | | VThread C |        |
|  └───────────┘ └───────────┘ └───────────┘        |
|  阻塞时挂起 → 平台线程可以继续调度其他虚拟线程 |
+------------------------------------------------------+
+------------------------------------------------------+
|  Platform Thread 2                                 |
|  ┌───────────┐ ┌───────────┐ ┌───────────┐        |
|  | VThread D | | VThread E | | VThread F |        |
|  └───────────┘ └───────────┘ └───────────┘        |
+------------------------------------------------------+
特点：
- 多个虚拟线程映射到少数平台线程（M:N）
- 阻塞时虚拟线程挂起，不占用平台线程
- 高并发、大量阻塞场景效率高

Development environment

JDK 21 (GraalVM distribution)

Maven 3.9.11

Spring Boot 3.5.6

Project setup (pom.xml)

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.5.6</version>
</parent>

<properties>
  <maven.compiler.source>21</maven.compiler.source>
  <maven.compiler.target>21</maven.compiler.target>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
      <exclusion>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-logging</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
</dependencies>

The above pom uses Spring Boot 3.5.6, JDK 21, and the Web starter. Additional dependencies can be added as required.

Enable virtual threads

Add a single property to the application configuration. According to the Spring Boot documentation, setting spring.threads.virtual.enabled to true activates virtual‑thread support on JDK 21.

spring:
  threads:
    virtual:
      enabled: true

Verification controller

package com.uav;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {
    @RequestMapping("/users")
    public String getUsers() {
        System.err.println(Thread.currentThread().getName());
        return "OK";
    }
}

When the spring.threads.virtual.enabled flag is false (or omitted), a request to /users prints a platform thread name such as http-nio-8080-exec-1. After enabling virtual threads, the same request prints a name like tomcat-handler-0, confirming that Tomcat is executing the request on a virtual thread.

Conclusion

With JDK 21, Spring Boot applications can switch to virtual threads by adding a single configuration property. This change dramatically reduces per‑thread memory consumption and allows the application to handle far higher concurrent loads on modest hardware. Virtual threads do not inherently speed up individual request processing, but they improve overall stability and resource efficiency under heavy traffic.