java-concurrency

---
name: java-concurrency
description: Implement modern concurrency with Virtual Threads and Structured Concurrency in Java. Use when implementing Java Virtual Threads (Java 21), Structured Concurrency with StructuredTaskScope, CompletableFuture pipelines, or debugging race conditions.
metadata:
  triggers:
    files:
    - '**/*.java'
    keywords:
    - Thread
    - Executor
    - synchronized
    - lock
    - CompletableFuture
    - StructuredTaskScope
    - VirtualThread
    - AtomicInteger
    - async
    - race condition
---
# Java Concurrency

## **Priority: P1 (HIGH)**


## Implementation Guidelines

- **Virtual Threads (Java 21)**: Use for high-throughput I/O. `Executors.newVirtualThreadPerTaskExecutor()`.
- **Structured Concurrency**: Use `StructuredTaskScope` to treat related tasks as single unit (Scope, Fork, Join).
- **Immutability**: Share immutable data between threads to avoid race conditions.
- **CompletableFuture**: Use for composing async pipelines (if not using Virtual Threads).
- **Atomic Variables**: Use `AtomicInteger`, `LongAdder` for simple counters.
- **Locks**: Prefer `ReentrantLock` / `ReadWriteLock` over `synchronized` for fine-grained control.
- **Thread Safety**: Document `@ThreadSafe` or `@NotThreadSafe`.

## Anti-Patterns

- **No new Thread()**: Use Executors or virtual threads; never create threads manually.
- **No Pooling Virtual Threads**: Virtual threads cheap; never pool them.
- **No Blocking in synchronized**: Pins carrier thread (Loom pitfall); use ReentrantLock instead.
- **No Shared Mutable State**: Share only immutable data between threads.
- **No Thread.stop/suspend**: Deprecated; use interruption or cancellation instead.

## References

- [StructuredTaskScope & VirtualThread Examples](references/structured-concurrency.md)