125-java-concurrency

# Java rules for Concurrency objects

Identify and apply Java concurrency best practices to improve thread safety, scalability, and maintainability by using modern `java.util.concurrent` utilities, virtual threads, and structured concurrency.

**Core areas:** Thread safety fundamentals (`ConcurrentHashMap`, `AtomicInteger`, `ReentrantLock`, `ReadWriteLock`, Java Memory Model), `ExecutorService` thread pool configuration (sizing, keep-alive, bounded queues, rejection policies, graceful shutdown), Producer-Consumer and Publish-Subscribe concurrent design patterns (`BlockingQueue`), `CompletableFuture` for non-blocking async composition (`thenApply`/`thenCompose`/`exceptionally`/`orTimeout`), immutability and safe publication (`volatile`, static initializers), lock contention and false-sharing performance optimization, virtual threads (`Executors.newVirtualThreadPerTaskExecutor()`) for I/O-bound scalability, `StructuredTaskScope` for lifecycle-scoped task management, `ScopedValue` over `ThreadLocal` for immutable cross-task data, cooperative cancellation and `InterruptedException` discipline, backpressure with bounded queues and `CallerRunsPolicy`, deadlock avoidance via global lock ordering and `tryLock` with timeouts, `ForkJoin`/parallel-stream discipline for CPU-bound work, virtual-thread pinning detection (JFR `VirtualThreadPinned`), thread naming and `UncaughtExceptionHandler` observability, and fit-for-purpose primitives (`LongAdder`, `CopyOnWriteArrayList`, `StampedLock`, `Semaphore`, `CountDownLatch`, `Phaser`).

**Prerequisites:** Run `./mvnw compile` or `mvn compile` before applying any change. If compilation fails, **stop immediately** — compilation failure is a blocking condition that prevents any further processing.

**Multi-step scope:** Step 1 validates the project compiles. Step 2 analyzes existing concurrency patterns and categorizes issues by impact (CRITICAL, MAINTAINABILITY, PERFORMANCE, SCALABILITY). Step 3 applies thread safety fundamentals — replacing unsafe collections with `java.util.concurrent` equivalents and atomic classes. Step 4 refactors thread pool management to use properly configured `ExecutorService` instances with bounded queues and rejection policies. Step 5 implements concurrent design patterns (Producer-Consumer via `BlockingQueue`, Publish-Subscribe). Step 6 migrates asynchronous operations to `CompletableFuture` with proper chaining and timeout handling. Step 7 adopts modern Java concurrency features — virtual threads for I/O-bound tasks, `StructuredTaskScope` for related task groups, and `ScopedValue` instead of `ThreadLocal`. Step 8 enforces cancellation and interruption discipline — never swallowing `InterruptedException`, using `Future.cancel(true)`, and preferring `lockInterruptibly`. Step 9 adds backpressure and overload protection — bounded queues, semaphores/bulkheads, and `CallerRunsPolicy`. Step 10 eliminates deadlock risks via lock ordering, minimized lock scope, and `tryLock` with timeouts. Step 11 adds observability — named threads, `UncaughtExceptionHandler`, JFR metrics, and structured logging. Step 12 runs `./mvnw clean verify` to confirm all tests pass after changes.

**Before applying changes:** Read the reference for detailed good/bad examples, constraints, and safeguards for each concurrency pattern.

## Reference

For detailed guidance, examples, and constraints, see [references/125-java-concurrency.md](references/125-java-concurrency.md).