Virtual Thread Support#

Resilience4j added comprehensive Java 21 virtual thread (Project Loom) support in PR #2335. The feature is opt-in and fully backward-compatible — existing applications continue to use platform threads unless explicitly configured otherwise. 1

Configuration#

Thread type is resolved in priority order 2:

1. JVM system property: -Dresilience4j.thread.type=virtual
2. Environment variable: RESILIENCE4J_THREAD_TYPE=virtual
3. Default: platform

Spring Boot 3/4 auto-configuration exposes the same setting as a YAML property:

resilience4j:
  thread:
    type: virtual

Auto-configuration classes (Resilience4jThreadAutoConfiguration, ThreadMetricsAutoConfiguration) are registered in META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. 1

Core Abstractions#

ThreadType enum#

ThreadType (resilience4j-core) has two constants — VIRTUAL and PLATFORM — with PLATFORM as the default. Use ThreadType.fromString(value) (case-insensitive) or the safe ThreadType.fromStringOrDefault(value, default) to parse configuration strings. 3

ExecutorServiceFactory#

ExecutorServiceFactory is the central factory for all internal ScheduledExecutorService instances. Key methods:

• getThreadType() — reads the system property / env var and returns the active ThreadType.
• newSingleThreadScheduledExecutor(poolName) — creates a single-thread scheduler, virtual or platform depending on configuration.
• newScheduledThreadPool(size, poolName) — creates a fixed-size pool.

Virtual threads are named {poolName}-vthread-0, {poolName}-vthread-1, etc.; platform threads use {poolName}-thread-N with daemon mode. 4

Consumers: FixedThreadPoolBulkhead, SchedulerFactory (circuit breaker), and SemaphoreBasedRateLimiter all delegate to this factory. 1

Registry Store: FutureHashMap Pattern#

The most critical virtual-thread-specific design is in InMemoryRegistryStore.

Problem: ConcurrentHashMap.computeIfAbsent() holds a segment lock while the mapping function runs. If the mapping function blocks (I/O, DB call, expensive initialization), virtual threads get pinned to their carrier thread — eliminating the scalability benefit of virtual threads. 5

Solution — FutureHashMap pattern 6:

The map stores CompletableFuture<E> values instead of E directly. computeIfAbsent uses ConcurrentHashMap.putIfAbsent (no lock held during execution) to race threads for a slot:

• Winner thread — inserts a new incomplete CompletableFuture, runs mappingFunction.apply() outside any map lock, then calls future.complete(value).
• Loser threads — call future.join(), which parks via LockSupport.park() — virtual-thread-friendly, no carrier thread blocking.
• Failure handling — if the mapping function throws, completeExceptionally() is called; the entry is removed only if the caller won the completeExceptionally CAS, avoiding race conditions. 7

Benchmark results from the PR show this approach achieves 101.2 ops/s at 100 concurrent virtual threads vs. 25.9 ops/s with a plain ConcurrentHashMap (which caused thread pinning). 1

⚠️ Do not simplify computeIfAbsent back to the standard ConcurrentHashMap version — the comment in the source explicitly flags this as intentional and notes that a future JDK simplification may be possible only when JDK 25 optimizes computeIfAbsent internally. 5

All other InMemoryRegistryStore operations (putIfAbsent, remove, replace, values) also operate on CompletableFuture<E> entries and use future.join() for retrieval, maintaining consistent virtual-thread-friendly behavior. 8

Concurrency correctness is tested in InMemoryRegistryStoreTest, which includes scenarios for concurrent computeIfAbsent + putIfAbsent, remove, replace, and failure injection via a slow/failing mapping function. 9

Module-Level Changes#

1

Key Source Files#