Comprehensive guide to Virtual Threads introduced in Java 21 as part of Project Loom, revolutionizing concurrent programming.

1. Virtual Threads Overview

Traditional vs Virtual Threads

public class VirtualThreadsOverview {
public static void main(String[] args) {
System.out.println("=== Virtual Threads vs Platform Threads ===");
// Platform Thread (traditional)
Thread platformThread = new Thread(() -> {
System.out.println("Platform Thread: " + Thread.currentThread());
System.out.println("Is Virtual: " + Thread.currentThread().isVirtual());
});
// Virtual Thread (new in Java 21)
Thread virtualThread = Thread.ofVirtual().start(() -> {
System.out.println("Virtual Thread: " + Thread.currentThread());
System.out.println("Is Virtual: " + Thread.currentThread().isVirtual());
});
try {
platformThread.join();
virtualThread.join();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
}

Key Characteristics

public class VirtualThreadCharacteristics {
public static void demonstrateCharacteristics() {
System.out.println("=== Virtual Threads Characteristics ===");
// 1. Lightweight - can create millions
Runnable task = () -> {
System.out.println("Executing in: " + Thread.currentThread());
System.out.println("Is Virtual: " + Thread.currentThread().isVirtual());
System.out.println("Thread ID: " + Thread.currentThread().threadId());
System.out.println("Is Daemon: " + Thread.currentThread().isDaemon());
};
// Create multiple virtual threads
for (int i = 0; i < 5; i++) {
Thread virtualThread = Thread.ofVirtual().start(task);
}
// Virtual threads are always daemon threads
Thread virtualThread = Thread.ofVirtual().unstarted(task);
System.out.println("Before start - Is Daemon: " + virtualThread.isDaemon());
virtualThread.start();
}
}

2. Creating Virtual Threads

Different Creation Methods

public class VirtualThreadCreation {
public static void main(String[] args) throws Exception {
System.out.println("=== Virtual Thread Creation Methods ===");
// Method 1: Thread.ofVirtual().start()
Thread vThread1 = Thread.ofVirtual().start(() -> {
System.out.println("Method 1 - Direct start: " + Thread.currentThread().getName());
});
// Method 2: Thread.ofVirtual().unstarted() + start()
Thread vThread2 = Thread.ofVirtual()
.name("custom-virtual-thread-1")
.unstarted(() -> {
System.out.println("Method 2 - Unstarted: " + Thread.currentThread().getName());
});
vThread2.start();
// Method 3: Thread.startVirtualThread() (convenience method)
Thread vThread3 = Thread.startVirtualThread(() -> {
System.out.println("Method 3 - Start virtual: " + Thread.currentThread().getName());
});
// Method 4: Using Executors
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
executor.submit(() -> {
System.out.println("Method 4 - Executor: " + Thread.currentThread().getName());
});
}
vThread1.join();
vThread2.join();
vThread3.join();
}
}

Builder Pattern for Configuration

public class VirtualThreadBuilder {
public static void demonstrateBuilder() {
System.out.println("=== Virtual Thread Builder ===");
// Configure virtual thread with builder
Thread.Builder builder = Thread.ofVirtual()
.name("worker-", 0)  // name pattern and start index
.inheritInheritableThreadLocals(false); // control inheritance
// Create multiple threads with sequential names
for (int i = 0; i < 3; i++) {
Thread virtualThread = builder.start(() -> {
System.out.println("Thread: " + Thread.currentThread().getName() + 
", Virtual: " + Thread.currentThread().isVirtual());
});
}
// Factory method for unstarted threads
Thread unstarted = Thread.ofVirtual()
.name("unstarted-worker")
.unstarted(() -> {
System.out.println("This won't print until started");
});
System.out.println("Created unstarted thread: " + unstarted.getName());
unstarted.start(); // Now it will execute
}
}

3. Executors with Virtual Threads

Virtual Thread Executors

public class VirtualThreadExecutors {
public static void main(String[] args) throws Exception {
System.out.println("=== Virtual Thread Executors ===");
// Method 1: newVirtualThreadPerTaskExecutor (recommended)
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<Future<String>> futures = new ArrayList<>();
for (int i = 0; i < 10; i++) {
int taskId = i;
Future<String> future = executor.submit(() -> {
Thread.sleep(100); // Simulate work
return "Task-" + taskId + " completed by " + 
Thread.currentThread().getName();
});
futures.add(future);
}
// Collect results
for (Future<String> future : futures) {
System.out.println(future.get());
}
}
// Method 2: newThreadPerTaskExecutor with virtual thread factory
ThreadFactory virtualThreadFactory = Thread.ofVirtual().factory();
try (var executor = Executors.newThreadPerTaskExecutor(virtualThreadFactory)) {
executor.submit(() -> {
System.out.println("Using custom factory: " + Thread.currentThread().getName());
});
}
}
}

ExecutorService Patterns

public class ExecutorServicePatterns {
public void processUsers(List<String> userIds) throws Exception {
System.out.println("=== Processing with Virtual Threads ===");
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
// Submit all tasks
List<CompletableFuture<UserProfile>> futures = userIds.stream()
.map(userId -> CompletableFuture.supplyAsync(() -> 
fetchUserProfile(userId), executor))
.toList();
// Wait for all completions
CompletableFuture<Void> allFutures = CompletableFuture.allOf(
futures.toArray(new CompletableFuture[0])
);
// Get results
List<UserProfile> profiles = allFutures
.thenApply(v -> futures.stream()
.map(CompletableFuture::join)
.toList())
.join();
System.out.println("Processed " + profiles.size() + " users");
}
}
public void batchProcessing(List<Order> orders) throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<OrderResult>> futures = orders.stream()
.map(order -> CompletableFuture.supplyAsync(() -> 
processOrder(order), executor))
.toList();
// Process as they complete
CompletableFuture<?>[] futureArray = futures.toArray(new CompletableFuture[0]);
CompletableFuture.anyOf(futureArray)
.thenAccept(result -> {
System.out.println("First order completed: " + result);
});
// Wait for all
CompletableFuture.allOf(futureArray).join();
}
}
private UserProfile fetchUserProfile(String userId) {
// Simulate API call
try {
Thread.sleep(100);
return new UserProfile(userId, "User-" + userId);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}
private OrderResult processOrder(Order order) {
// Simulate order processing
try {
Thread.sleep(200);
return new OrderResult(order.id(), "PROCESSED");
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}
record UserProfile(String id, String name) {}
record Order(String id, double amount) {}
record OrderResult(String orderId, String status) {}
}

4. I/O Operations with Virtual Threads

Non-blocking I/O Patterns

public class VirtualThreadsIO {
public CompletableFuture<List<String>> fetchMultipleUrls(List<String> urls) {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<String>> futures = urls.stream()
.map(url -> CompletableFuture.supplyAsync(() -> 
fetchUrl(url), executor))
.toList();
return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
.thenApply(v -> futures.stream()
.map(CompletableFuture::join)
.toList());
}
}
private String fetchUrl(String url) {
// Simulate HTTP request
try {
Thread.sleep(100 + (long) (Math.random() * 100));
return "Response from " + url;
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}
public void databaseOperations() throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<Void>> operations = new ArrayList<>();
// Simulate multiple database operations
for (int i = 0; i < 1000; i++) {
int recordId = i;
CompletableFuture<Void> operation = CompletableFuture.runAsync(() -> {
processDatabaseRecord(recordId);
}, executor);
operations.add(operation);
}
// Wait for all operations to complete
CompletableFuture.allOf(operations.toArray(new CompletableFuture[0])).join();
System.out.println("All database operations completed");
}
}
private void processDatabaseRecord(int recordId) {
// Simulate database operation
try {
Thread.sleep(50);
System.out.println("Processed record: " + recordId + " on " + 
Thread.currentThread().getName());
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
}

File Processing Example

public class FileProcessingWithVirtualThreads {
public void processFilesConcurrently(List<java.nio.file.Path> files) throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<FileProcessResult>> futures = files.stream()
.map(file -> CompletableFuture.supplyAsync(() -> 
processFile(file), executor))
.toList();
List<FileProcessResult> results = futures.stream()
.map(CompletableFuture::join)
.toList();
System.out.println("Processed " + results.size() + " files");
}
}
private FileProcessResult processFile(java.nio.file.Path file) {
try {
// Simulate file processing
Thread.sleep(100);
long size = Files.size(file);
return new FileProcessResult(file.getFileName().toString(), size, "SUCCESS");
} catch (Exception e) {
return new FileProcessResult(file.getFileName().toString(), 0, "ERROR: " + e.getMessage());
}
}
public void batchFileOperations() throws Exception {
List<java.nio.file.Path> files = List.of(
java.nio.file.Path.of("file1.txt"),
java.nio.file.Path.of("file2.txt"),
java.nio.file.Path.of("file3.txt")
);
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
// Read all files concurrently
List<CompletableFuture<List<String>>> readFutures = files.stream()
.map(file -> CompletableFuture.supplyAsync(() -> 
readFileLines(file), executor))
.toList();
// Process results as they complete
for (CompletableFuture<List<String>> future : readFutures) {
List<String> lines = future.get();
System.out.println("Read " + lines.size() + " lines");
}
}
}
private List<String> readFileLines(java.nio.file.Path file) {
try {
Thread.sleep(50); // Simulate I/O
return Files.readAllLines(file);
} catch (Exception e) {
return List.of();
}
}
record FileProcessResult(String filename, long size, String status) {}
}

5. Error Handling and Cancellation

Proper Error Handling

public class VirtualThreadsErrorHandling {
public void demonstrateErrorHandling() throws Exception {
System.out.println("=== Error Handling in Virtual Threads ===");
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<String>> futures = new ArrayList<>();
for (int i = 0; i < 5; i++) {
int taskId = i;
CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
if (taskId == 2) {
throw new RuntimeException("Simulated failure in task " + taskId);
}
return "Task-" + taskId + " succeeded";
}, executor)
.exceptionally(ex -> "Task failed: " + ex.getMessage());
futures.add(future);
}
// Collect results including failures
for (CompletableFuture<String> future : futures) {
System.out.println(future.get());
}
}
}
public void handleTimeouts() throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
try {
Thread.sleep(5000); // Long operation
return "Result";
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
return "Interrupted";
}
}, executor);
try {
String result = future.get(1, TimeUnit.SECONDS); // Timeout after 1 second
System.out.println("Got result: " + result);
} catch (TimeoutException e) {
System.out.println("Task timed out");
future.cancel(true); // Cancel the task
}
}
}
public void resourceCleanup() throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
CompletableFuture<Void> task = CompletableFuture.runAsync(() -> {
try (var resource = new AutoCloseableResource()) {
resource.use();
Thread.sleep(100);
} catch (Exception e) {
Thread.currentThread().interrupt();
}
}, executor);
task.get(); // Wait for completion with proper resource cleanup
}
}
static class AutoCloseableResource implements AutoCloseable {
public void use() {
System.out.println("Using resource in: " + Thread.currentThread().getName());
}
@Override
public void close() {
System.out.println("Closing resource from: " + Thread.currentThread().getName());
}
}
}

6. Synchronization and Coordination

Structured Concurrency

public class StructuredConcurrencyExample {
public UserProfile fetchUserData(String userId) throws Exception {
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
// Fork subtasks
StructuredTaskScope.Subtask<String> userSubtask = scope.fork(() -> 
fetchUserDetails(userId));
StructuredTaskScope.Subtask<List<String>> ordersSubtask = scope.fork(() -> 
fetchUserOrders(userId));
StructuredTaskScope.Subtask<List<String>> preferencesSubtask = scope.fork(() -> 
fetchUserPreferences(userId));
// Wait for all subtasks to complete or any to fail
scope.join();
scope.throwIfFailed(); // Propagate any exception
// Combine results
return new UserProfile(
userSubtask.get(),
ordersSubtask.get(),
preferencesSubtask.get()
);
}
}
public UserProfile fetchUserDataWithTimeout(String userId) throws Exception {
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
StructuredTaskScope.Subtask<String> userSubtask = scope.fork(() -> 
fetchUserDetails(userId));
StructuredTaskScope.Subtask<List<String>> ordersSubtask = scope.fork(() -> 
fetchUserOrders(userId));
// Wait with timeout
scope.joinUntil(Instant.now().plusSeconds(5));
if (userSubtask.state() == StructuredTaskScope.Subtask.State.SUCCESS &&
ordersSubtask.state() == StructuredTaskScope.Subtask.State.SUCCESS) {
return new UserProfile(userSubtask.get(), ordersSubtask.get(), List.of());
} else {
throw new TimeoutException("Failed to fetch user data within timeout");
}
}
}
private String fetchUserDetails(String userId) {
try {
Thread.sleep(100);
return "User details for " + userId;
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}
private List<String> fetchUserOrders(String userId) {
try {
Thread.sleep(200);
return List.of("Order1", "Order2");
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}
private List<String> fetchUserPreferences(String userId) {
try {
Thread.sleep(150);
return List.of("Pref1", "Pref2");
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
throw new RuntimeException(e);
}
}
record UserProfile(String details, List<String> orders, List<String> preferences) {}
}

7. Performance and Best Practices

Performance Comparison

public class VirtualThreadsPerformance {
public static void main(String[] args) throws Exception {
int taskCount = 10_000;
System.out.println("=== Performance Comparison ===");
// Platform threads
long platformTime = measurePlatformThreads(taskCount);
System.out.printf("Platform threads: %d ms%n", platformTime);
// Virtual threads
long virtualTime = measureVirtualThreads(taskCount);
System.out.printf("Virtual threads: %d ms%n", virtualTime);
System.out.printf("Improvement: %.2fx faster%n", (double) platformTime / virtualTime);
}
private static long measurePlatformThreads(int taskCount) throws Exception {
long startTime = System.currentTimeMillis();
try (var executor = Executors.newFixedThreadPool(200)) {
List<CompletableFuture<Void>> futures = new ArrayList<>();
for (int i = 0; i < taskCount; i++) {
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
try {
Thread.sleep(10); // Simulate I/O
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}, executor);
futures.add(future);
}
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
}
return System.currentTimeMillis() - startTime;
}
private static long measureVirtualThreads(int taskCount) throws Exception {
long startTime = System.currentTimeMillis();
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<Void>> futures = new ArrayList<>();
for (int i = 0; i < taskCount; i++) {
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
try {
Thread.sleep(10); // Simulate I/O
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}, executor);
futures.add(future);
}
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
}
return System.currentTimeMillis() - startTime;
}
}

Best Practices

public class VirtualThreadsBestPractices {
// ✅ DO: Use for I/O-bound tasks
public void ioBoundOperations() throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<String>> futures = List.of(
CompletableFuture.supplyAsync(() -> fetchFromDatabase("query1"), executor),
CompletableFuture.supplyAsync(() -> callExternalApi("api1"), executor),
CompletableFuture.supplyAsync(() -> readFromFile("file1"), executor)
);
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
}
}
// ❌ DON'T: Use for CPU-bound tasks
public void cpuBoundOperations() {
// Virtual threads don't help with CPU-bound work
// Use platform threads or ForkJoinPool instead
List<CompletableFuture<Void>> futures = new ArrayList<>();
for (int i = 0; i < Runtime.getRuntime().availableProcessors(); i++) {
futures.add(CompletableFuture.runAsync(() -> {
intensiveComputation(); // CPU-bound
}));
}
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
}
// ✅ DO: Use structured concurrency for related tasks
public void structuredApproach(String userId) throws Exception {
try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
var userTask = scope.fork(() -> fetchUser(userId));
var profileTask = scope.fork(() -> fetchProfile(userId));
var settingsTask = scope.fork(() -> fetchSettings(userId));
scope.join();
scope.throwIfFailed();
return combineData(userTask.get(), profileTask.get(), settingsTask.get());
}
}
// ✅ DO: Proper resource cleanup
public void withResources() throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
CompletableFuture.runAsync(() -> {
try (var connection = getDatabaseConnection();
var statement = connection.createStatement()) {
// Use resources
processData(statement);
} catch (Exception e) {
throw new RuntimeException(e);
}
}, executor).join();
}
}
private String fetchFromDatabase(String query) {
try { Thread.sleep(100); return "result"; } 
catch (InterruptedException e) { throw new RuntimeException(e); }
}
private String callExternalApi(String api) {
try { Thread.sleep(200); return "response"; } 
catch (InterruptedException e) { throw new RuntimeException(e); }
}
private String readFromFile(String file) {
try { Thread.sleep(50); return "content"; } 
catch (InterruptedException e) { throw new RuntimeException(e); }
}
private void intensiveComputation() {
// CPU-intensive work
long result = 0;
for (long i = 0; i < 1_000_000_000; i++) {
result += i;
}
}
// Placeholder methods
private Object getDatabaseConnection() { return null; }
private void processData(Object statement) {}
private String fetchUser(String userId) { return null; }
private String fetchProfile(String userId) { return null; }
private String fetchSettings(String userId) { return null; }
private Object combineData(String user, String profile, String settings) { return null; }
}

8. Migration from Traditional Threading

Before and After Examples

public class MigrationExamples {
// Before: Traditional thread pool for I/O
public void oldStyleIoProcessing(List<String> urls) throws Exception {
ExecutorService executor = Executors.newFixedThreadPool(100);
try {
List<Future<String>> futures = new ArrayList<>();
for (String url : urls) {
futures.add(executor.submit(() -> {
// I/O operation
return fetchUrl(url);
}));
}
for (Future<String> future : futures) {
String result = future.get();
processResult(result);
}
} finally {
executor.shutdown();
}
}
// After: Virtual threads for I/O
public void newStyleIoProcessing(List<String> urls) throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<String>> futures = urls.stream()
.map(url -> CompletableFuture.supplyAsync(() -> 
fetchUrl(url), executor))
.toList();
futures.forEach(future -> {
try {
processResult(future.get());
} catch (Exception e) {
// Handle exception
}
});
}
}
// Before: Complex async handling
public void oldStyleAsyncOperations() throws Exception {
ExecutorService executor = Executors.newCachedThreadPool();
CompletionService<String> completionService = new ExecutorCompletionService<>(executor);
// Submit tasks
for (int i = 0; i < 10; i++) {
int taskId = i;
completionService.submit(() -> "Result-" + taskId);
}
// Process results
for (int i = 0; i < 10; i++) {
Future<String> future = completionService.take();
String result = future.get();
System.out.println(result);
}
executor.shutdown();
}
// After: Simplified with virtual threads
public void newStyleAsyncOperations() throws Exception {
try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
List<CompletableFuture<String>> futures = new ArrayList<>();
for (int i = 0; i < 10; i++) {
int taskId = i;
futures.add(CompletableFuture.supplyAsync(() -> 
"Result-" + taskId, executor));
}
// Process as they complete
for (CompletableFuture<String> future : futures) {
System.out.println(future.get());
}
}
}
private String fetchUrl(String url) {
try { Thread.sleep(100); return "data"; } 
catch (InterruptedException e) { throw new RuntimeException(e); }
}
private void processResult(String result) {
// Process the result
}
}

Key Benefits Summary

Virtual Threads in Java 21 represent a fundamental shift in Java concurrency, making it much easier to write, maintain, and scale concurrent applications, particularly those that are I/O-bound.