java-concurrency

name	java-concurrency
description	Modern concurrency patterns using Virtual Threads and Structured Concurrency. Use when implementing Java Virtual Threads (Java 21), Structured Concurrency with StructuredTaskScope, CompletableFuture pipelines, or debugging race conditions. (triggers: **/*.java, Thread, Executor, synchronized, lock, CompletableFuture, StructuredTaskScope, VirtualThread, AtomicInteger, async, race condition)

Java Concurrency

Priority: P1 (HIGH)

Modern concurrent programming emphasizing Virtual Threads (Loom) and safety.

Implementation Guidelines

• Virtual Threads (Java 21): Use for high-throughput I/O. Executors.newVirtualThreadPerTaskExecutor().
• Structured Concurrency: Use StructuredTaskScope to treat related tasks as a 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 are 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