MACRO NEPAL
Pinning Virtual Threads to Carriers in Java
awiskar acharya
November 13, 2025
11:36 am

Introduction

Virtual Threads in Java 21+ introduce a lightweight concurrency model, but understanding carrier thread pinning is crucial for optimal performance. Pinning occurs when a virtual thread gets temporarily bound to its carrier thread, potentially reducing concurrency benefits.

Understanding Virtual Thread Architecture

Virtual Thread vs Platform Thread

public class VirtualThreadArchitecture {
public void demonstrateThreadTypes() {
// Platform thread (heavyweight)
Thread platformThread = new Thread(() -> {
System.out.println("Platform thread: " + Thread.currentThread());
});
// Virtual thread (lightweight)
Thread virtualThread = Thread.ofVirtual()
.name("virtual-thread-", 0)
.start(() -> {
System.out.println("Virtual thread: " + Thread.currentThread());
System.out.println("Is virtual: " + Thread.currentThread().isVirtual());
});
// Virtual thread with factory
ThreadFactory virtualFactory = Thread.ofVirtual().factory();
Thread virtualFromFactory = virtualFactory.newThread(() -> {
System.out.println("From factory: " + Thread.currentThread());
});
virtualFromFactory.start();
}
}

What is Carrier Pinning?

The Pinning Mechanism

public class CarrierPinningExplanation {
// Carrier threads are platform threads from ForkJoinPool that execute virtual threads
public void demonstratePinningScenarios() {
// Scenario 1: Synchronized block - causes pinning
Thread virtualThread1 = Thread.ofVirtual().start(() -> {
synchronized (this) {  // This will pin the virtual thread
System.out.println("Inside synchronized - pinned: " + 
Thread.currentThread().isVirtual());
try {
Thread.sleep(100);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
});
// Scenario 2: Native method calls - may cause pinning
Thread virtualThread2 = Thread.ofVirtual().start(() -> {
System.out.println("Before native call");
System.out.println("After native call - still virtual: " + 
Thread.currentThread().isVirtual());
});
// Scenario 3: File I/O operations - may cause pinning
Thread virtualThread3 = Thread.ofVirtual().start(() -> {
try {
Files.readAllLines(Path.of("test.txt"));  // May cause pinning
System.out.println("After file I/O: " + Thread.currentThread().isVirtual());
} catch (IOException e) {
e.printStackTrace();
}
});
}
}

Detecting and Monitoring Pinning

Pinning Detection Tools

public class PinningDetection {
// JVM options to monitor pinning:
// -Djdk.tracePinnedThreads=full
// -Djdk.tracePinnedThreads=short
public void demonstratePinningDetection() {
Thread virtualThread = Thread.ofVirtual().start(() -> {
// This synchronized block will trigger pinning warning
synchronized (this) {
try {
System.out.println("Working in pinned state...");
Thread.sleep(500);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
});
try {
virtualThread.join();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
// Programmatic pinning monitoring
public void monitorPinningProgrammatically() {
Thread virtualThread = Thread.ofVirtual()
.unstarted(() -> performBlockingOperation());
// Add uncaught exception handler to detect issues
virtualThread.setUncaughtExceptionHandler((thread, throwable) -> {
System.err.println("Virtual thread error: " + throwable.getMessage());
});
virtualThread.start();
}
private void performBlockingOperation() {
synchronized (this) {
System.out.println("Carrier thread: " + Thread.currentThread());
System.out.println("Is virtual: " + Thread.currentThread().isVirtual());
// Check if we're pinned
if (isPinned()) {
System.out.println("WARNING: Virtual thread is pinned to carrier!");
}
}
}
private boolean isPinned() {
// This is a simplified check - actual pinning detection
// requires more sophisticated monitoring
StackTraceElement[] stackTrace = Thread.currentThread().getStackTrace();
for (StackTraceElement element : stackTrace) {
if (element.getMethodName().contains("synchronized")) {
return true;
}
}
return false;
}
}

Avoiding Pinning with Best Practices

Replacing Synchronized with ReentrantLock

public class PinningAvoidance {
private final ReentrantLock lock = new ReentrantLock();
private final AtomicInteger counter = new AtomicInteger(0);
public void demonstrateLockInsteadOfSynchronized() {
Thread virtualThread = Thread.ofVirtual().start(() -> {
// Using ReentrantLock instead of synchronized avoids pinning
lock.lock();
try {
System.out.println("Lock acquired without pinning: " + 
Thread.currentThread().isVirtual());
// Simulate work
int current = counter.incrementAndGet();
System.out.println("Counter: " + current);
// This won't pin the virtual thread
try {
Thread.sleep(100);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
} finally {
lock.unlock();
}
});
}
// Using Semaphore for resource control
private final Semaphore semaphore = new Semaphore(5);
public void demonstrateSemaphoreUsage() {
for (int i = 0; i < 10; i++) {
Thread virtualThread = Thread.ofVirtual().start(() -> {
try {
semaphore.acquire();
try {
System.out.println("Semaphore acquired by: " + 
Thread.currentThread().getName());
// Work without pinning
processItem();
} finally {
semaphore.release();
}
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
});
}
}
private void processItem() {
try {
Thread.sleep(50);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
}
}

Async I/O Operations

public class AsyncIOOperations {
public void demonstrateAsyncFileOperations() {
Thread virtualThread = Thread.ofVirtual().start(() -> {
try {
// Using async file operations to avoid pinning
CompletableFuture<String> fileContent = readFileAsync("data.txt");
fileContent.thenAccept(content -> {
System.out.println("File content length: " + content.length());
System.out.println("Still virtual after async I/O: " + 
Thread.currentThread().isVirtual());
}).join(); // Be careful with join in virtual threads
} catch (Exception e) {
e.printStackTrace();
}
});
}
private CompletableFuture<String> readFileAsync(String filename) {
return CompletableFuture.supplyAsync(() -> {
try {
return Files.readString(Path.of(filename));
} catch (IOException e) {
throw new RuntimeException("Failed to read file", e);
}
});
}
// Using HttpClient with virtual threads
public void demonstrateAsyncHttpClient() {
HttpClient client = HttpClient.newBuilder()
.executor(Executors.newVirtualThreadPerTaskExecutor())
.build();
for (int i = 0; i < 10; i++) {
Thread virtualThread = Thread.ofVirtual().start(() -> {
try {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://httpbin.org/delay/1"))
.build();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString());
System.out.println("Response status: " + response.statusCode() +
" from virtual thread: " + Thread.currentThread().isVirtual());
} catch (Exception e) {
e.printStackTrace();
}
});
}
}
}

Advanced Pinning Management

Custom Executor with Pinning Awareness

public class PinningAwareExecutor {
private final ExecService executorService;
public PinningAwareExecutor() {
this.executorService = new ExecService();
}
public <T> CompletableFuture<T> submit(Callable<T> task) {
return CompletableFuture.supplyAsync(() -> {
try {
return task.call();
} catch (Exception e) {
throw new RuntimeException(e);
}
}, executorService);
}
// Custom executor service that monitors pinning
private static class ExecService implements Executor {
private final ThreadFactory virtualThreadFactory = 
Thread.ofVirtual().factory();
@Override
public void execute(Runnable command) {
Thread virtualThread = virtualThreadFactory.newThread(() -> {
long startTime = System.nanoTime();
try {
command.run();
} finally {
long duration = System.nanoTime() - startTime;
// Log long-running operations that might indicate pinning
if (duration > 100_000_000L) { // 100ms threshold
System.out.println("Long operation detected: " + 
duration + " ns in thread: " + 
Thread.currentThread().getName());
}
}
});
virtualThread.start();
}
}
public void demonstratePinningAwareExecution() {
List<CompletableFuture<String>> futures = new ArrayList<>();
for (int i = 0; i < 5; i++) {
final int taskId = i;
CompletableFuture<String> future = submit(() -> {
if (taskId % 2 == 0) {
// Simulate blocking operation that might cause pinning
synchronized (this) {
Thread.sleep(100);
return "Pinned task " + taskId;
}
} else {
// Non-blocking operation
Thread.sleep(50);
return "Non-pinned task " + taskId;
}
});
futures.add(future);
}
// Wait for all tasks
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
.thenRun(() -> System.out.println("All tasks completed"))
.join();
}
}

Thread Local Management

public class ThreadLocalManagement {
// Scoped values (preferred over ThreadLocal for virtual threads)
private static final ScopedValue<String> USER_CONTEXT = ScopedValue.newInstance();
public void demonstrateScopedValues() {
// Using ScopedValue instead of ThreadLocal to avoid pinning
ScopedValue.where(USER_CONTEXT, "user123")
.run(() -> {
Thread virtualThread = Thread.ofVirtual().start(() -> {
String user = USER_CONTEXT.get();
System.out.println("User context: " + user + 
" in virtual thread: " + Thread.currentThread().isVirtual());
});
try {
virtualThread.join();
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
});
}
// If you must use ThreadLocal, be cautious
private static final ThreadLocal<String> LEGACY_THREAD_LOCAL = new ThreadLocal<>();
public void demonstrateThreadLocalWithVirtualThreads() {
Thread virtualThread = Thread.ofVirtual().start(() -> {
try {
LEGACY_THREAD_LOCAL.set("virtual-thread-data");
// Perform work
System.out.println("ThreadLocal value: " + LEGACY_THREAD_LOCAL.get());
System.out.println("Is virtual: " + Thread.currentThread().isVirtual());
} finally {
// Always clean up ThreadLocal to prevent memory leaks
LEGACY_THREAD_LOCAL.remove();
}
});
}
}

Performance Testing and Benchmarking

Pinning Impact Analysis

public class PinningBenchmark {
public void benchmarkPinnedVsNonPinned() throws InterruptedException {
int taskCount = 1000;
CountDownLatch latch = new CountDownLatch(taskCount);
long startTime = System.currentTimeMillis();
// Test with synchronized (pinning)
for (int i = 0; i < taskCount; i++) {
Thread.ofVirtual().start(() -> {
synchronized (this) {  // Causes pinning
try {
Thread.sleep(10);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
} finally {
latch.countDown();
}
}
});
}
latch.await();
long pinnedDuration = System.currentTimeMillis() - startTime;
// Test with ReentrantLock (no pinning)
ReentrantLock lock = new ReentrantLock();
CountDownLatch latch2 = new CountDownLatch(taskCount);
startTime = System.currentTimeMillis();
for (int i = 0; i < taskCount; i++) {
Thread.ofVirtual().start(() -> {
lock.lock();
try {
Thread.sleep(10);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
} finally {
lock.unlock();
latch2.countDown();
}
});
}
latch2.await();
long nonPinnedDuration = System.currentTimeMillis() - startTime;
System.out.println("Pinned execution time: " + pinnedDuration + "ms");
System.out.println("Non-pinned execution time: " + nonPinnedDuration + "ms");
System.out.println("Performance difference: " + 
((double) pinnedDuration / nonPinnedDuration) + "x");
}
// Memory usage comparison
public void memoryUsageComparison() {
Runtime runtime = Runtime.getRuntime();
// Test memory usage with many virtual threads
List<Thread> threads = new ArrayList<>();
long memoryBefore = runtime.totalMemory() - runtime.freeMemory();
for (int i = 0; i < 10_000; i++) {
Thread thread = Thread.ofVirtual().start(() -> {
try {
Thread.sleep(1000);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
});
threads.add(thread);
}
// Wait for threads to start
try {
Thread.sleep(100);
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
}
long memoryAfter = runtime.totalMemory() - runtime.freeMemory();
long memoryUsed = memoryAfter - memoryBefore;
System.out.println("Memory used by 10,000 virtual threads: " + 
(memoryUsed / 1024 / 1024) + " MB");
// Clean up
threads.forEach(Thread::interrupt);
}
}

Real-World Use Cases and Patterns

Web Server with Virtual Threads

public class VirtualThreadWebServer {
private final Server server;
private final ExecutorService virtualThreadExecutor;
public VirtualThreadWebServer() {
this.virtualThreadExecutor = Executors.newVirtualThreadPerTaskExecutor();
this.server = Server.builder()
.executor(virtualThreadExecutor)
.port(8080)
.handler(this::handleRequest)
.build();
}
public void start() throws IOException {
server.start();
System.out.println("Server started on port 8080 with virtual threads");
}
private void handleRequest(HttpServerRequest request, HttpServerResponse response) {
// Each request handled by a virtual thread
try {
String path = request.getPath();
switch (path) {
case "/fast" -> handleFastEndpoint(response);
case "/slow" -> handleSlowEndpoint(response);
case "/blocking" -> handleBlockingIO(response);
default -> handleNotFound(response);
}
} catch (Exception e) {
response.setStatus(500);
response.send("Internal Server Error");
}
}
private void handleFastEndpoint(HttpServerResponse response) {
response.send("Fast response from virtual thread: " + 
Thread.currentThread().isVirtual());
}
private void handleSlowEndpoint(HttpServerResponse response) {
// Simulate CPU-bound work without pinning
ReentrantLock lock = new ReentrantLock();
lock.lock();
try {
// Intensive computation
Thread.sleep(100);
response.send("Slow response completed");
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
response.setStatus(500);
response.send("Request interrupted");
} finally {
lock.unlock();
}
}
private void handleBlockingIO(HttpServerResponse response) {
// Using async I/O to avoid pinning
CompletableFuture.supplyAsync(() -> {
try {
// Simulate blocking I/O
Thread.sleep(200);
return "Blocking I/O completed";
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
}, virtualThreadExecutor).thenAccept(result -> {
response.send(result);
});
}
private void handleNotFound(HttpServerResponse response) {
response.setStatus(404);
response.send("Not Found");
}
public void stop() {
server.stop(0);
virtualThreadExecutor.close();
}
}

Database Access Patterns

public class DatabaseAccessWithVirtualThreads {
private final ExecutorService virtualThreadExecutor;
public DatabaseAccessWithVirtualThreads() {
this.virtualThreadExecutor = Executors.newVirtualThreadPerTaskExecutor();
}
public CompletableFuture<List<User>> getUsersConcurrently(List<String> userIds) {
List<CompletableFuture<User>> futures = userIds.stream()
.map(userId -> CompletableFuture.supplyAsync(() -> 
fetchUserFromDatabase(userId), virtualThreadExecutor))
.toList();
return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
.thenApply(v -> futures.stream()
.map(CompletableFuture::join)
.toList());
}
private User fetchUserFromDatabase(String userId) {
// Simulate database access
try {
// Using connection pool to avoid pinning
return useConnectionPool(userId);
} catch (Exception e) {
throw new RuntimeException("Failed to fetch user: " + userId, e);
}
}
private User useConnectionPool(String userId) throws InterruptedException {
// Simulate getting connection from pool
Thread.sleep(50);
// Use ReentrantLock instead of synchronized for database operations
ReentrantLock dbLock = new ReentrantLock();
dbLock.lock();
try {
// Database operation
return new User(userId, "User " + userId);
} finally {
dbLock.unlock();
}
}
// Batch processing with virtual threads
public CompletableFuture<Void> processBatch(List<DataItem> items) {
List<CompletableFuture<Void>> futures = items.stream()
.map(item -> CompletableFuture.runAsync(() -> 
processItem(item), virtualThreadExecutor))
.toList();
return CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]));
}
private void processItem(DataItem item) {
// Avoid synchronized blocks in processing
ReentrantLock processingLock = new ReentrantLock();
processingLock.lock();
try {
// Process item
System.out.println("Processing item: " + item.id() + 
" on virtual thread: " + Thread.currentThread().isVirtual());
Thread.sleep(10); // Simulate work
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
} finally {
processingLock.unlock();
}
}
record User(String id, String name) {}
record DataItem(String id, String content) {}
}

Best Practices Summary

  1. Avoid synchronized - Use ReentrantLock instead
  2. Use async I/O - Prefer CompletableFuture and NIO for I/O operations
  3. Monitor pinning - Use JVM flags and custom monitoring
  4. Clean ThreadLocals - Always remove ThreadLocal values or use ScopedValue
  5. Limit native calls - Be cautious with JNI and native method invocations
  6. Use proper executors - Leverage Executors.newVirtualThreadPerTaskExecutor()
  7. Test performance - Benchmark with and without potential pinning scenarios
  8. Profile applications - Use async profilers to identify pinning bottlenecks

Conclusion

Understanding and managing virtual thread pinning is essential for achieving optimal performance with Java's virtual threads. By following these patterns and best practices, developers can maximize the benefits of virtual threads while minimizing the performance impacts of carrier pinning. The key is to identify pinning scenarios early, use appropriate synchronization mechanisms, and leverage async patterns for I/O operations.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper