Java Concurrency

Java concurrency

Purpose

Translate requirements and evidence into the concurrency model with the clearest ownership, lifetime, cancellation, bounds, and failure semantics. Syntax does not create capacity: every in-flight operation consumes CPU, memory, connections, queue slots, downstream capacity, or recovery budget.

This category stops at one JVM. Cross-process retries, leases, ordering, and partial failure belong to distributed-system skills.

Classification contract

Start with the actual compiler release/toolchain, resolved framework versions, runtime image and preview policy. This router uses Java 21–25 as its reference range; the target project may be older. Neither adopting a construct nor reading a Java 25 source authorizes a JDK upgrade, new dependency or preview flag. Mark missing measurements as unknown and keep performance recommendations conditional rather than inventing a thread count.

unit of work and semantic result:
arrival shape: request/value/stream/scheduled/background
lifetime owner: lexical request/service/application
CPU demand, blocking/wait mechanisms and variability:
shared state, ordering and consistency requirements:
scarce resources and capacity per resource:
concurrency/admission/queue bounds and overload policy:
deadline, cancellation propagation and cleanup:
failure aggregation, retry/partial result policy:
context propagation and observability identity:
JDK/API status and framework constraints:

Route by dominant decision

Selection principles

• Concurrency and parallelism are independent quantities. Concurrency is overlapping work; parallelism is simultaneous execution. CPU throughput can also be limited by quota, memory bandwidth, locks, cache coherence, I/O completion, vectorization, or another device—not only a physical core count.
• Classify phases, not an entire service. One request can parse on CPU, block on a socket, contend on a pool, then execute CPU work. Choose boundaries and limits per phase.
• Cheap waiting does not create downstream capacity. Virtual threads can make a synchronous blocking style scalable when blockers cooperate, but connections, memory, APIs and quotas remain bounded.
• Lexical lifetime favors structured ownership, when a supported API/framework fits. Long-lived consumers, schedulers and supervisors need an explicit service lifecycle.
• A future is a value handle; reactive streams are a demand protocol. Do not select either only to avoid blocking syntax.
• State ownership precedes primitive choice. Prefer immutable snapshots/confinement when they match semantics; otherwise define atomic invariants and happens-before before locks/atomics.
• Overload behavior is part of correctness. Bound, reject, queue, shed, degrade, or backpressure deliberately; an unbounded queue transfers the bound to latency and heap. A semaphore or connection pool bounds active resource users, not the number of tasks waiting to acquire it. Also bound admission/waiters, acquisition time and retained request state.
• Cancellation is cooperative. Define propagation, interrupt behavior, noninterruptible calls, resource cleanup, partial side effects, and what happens after the caller leaves.

Evidence before “more threads”

Measure aligned:

arrival/completion/error/drop rate and in-flight work
queue depth/wait/service time per scarce resource
CPU by cgroup/process/thread and throttling
wall/off-CPU state and dependency/pool/lock duration
allocation/retained memory per in-flight operation
deadline/cancellation outcome and abandoned work

Low CPU plus high latency does not prove a queue, nor that adding concurrency helps. The system may be idle because of admission, timers, external wait, serial dependency, lost work, measurement scope, or traffic changes. Locate the wait and its owner.

Decision tree

one request/task with sequential blocking calls?
  -> synchronous style; consider virtual threads if concurrency and blocker support justify it
lexical fan-out whose subtasks must join/cancel together?
  -> structured concurrency if target API status is acceptable; otherwise explicit task-group ownership
callback-only or dependency graph of values?
  -> CompletableFuture/stage abstraction with explicit executor and cancellation bridge
unbounded/time-shaped stream with consumer demand?
  -> Reactive Streams or bounded queue/channel with protocol-level backpressure
CPU-decomposable finite computation?
  -> bounded parallel decomposition/ForkJoin after granularity and interference analysis
long-lived scheduled/consumer work?
  -> managed executor/supervisor with shutdown, retry and health semantics

These branches can coexist at explicit boundaries. Do not hide blocking work inside an event loop or CPU pool; do not wrap synchronous work in futures without defining the execution resource.

Version discipline

Virtual threads are final in Java 21; later JDKs change implementation details such as monitor pinning. Scoped values and structured concurrency have evolved through preview/incubator stages. In Java 25, ScopedValue is final while StructuredTaskScope is still preview; do not infer one API's status from the other. Scoped bindings do not make a mutable bound object immutable, and arbitrary executor submissions do not automatically inherit them. Before emitting source, verify the exact target JDK's JEP/API status, preview flags, binary/source compatibility, and framework/tooling support. Do not encode a moving API from memory.

Deliverable

Return the dominant decision and owning specialist skill, the selected model with its task owner and resource bound, one relevant rejected alternative, and the evidence/test that would confirm the choice. For an incident, separate observed waits from the suspected cause. Unknown workload or cancellation behavior is an explicit gap, not a capacity estimate. Keep this proportional; do not expand a routing answer into implementation of every listed construct.

Review checklist

• Every task has an owner, terminal state, deadline/cancel path, and cleanup.
• Every executor/scope/subscription has bounded admission and shutdown behavior.
• Scarce-resource bounds sit at the resource and are tested under saturation.
• Context cannot leak tenant/security state across reused threads/tasks.
• Blocking calls are known and do not occupy forbidden event-loop/CPU workers.
• Shared state has a stated JMM/thread-safety contract and compound invariants.
• Errors, partial success, retries and cancellation races preserve business semantics.
• Queue/in-flight/active/completion/rejection/cancellation metrics use bounded cardinality.
• Load, failure, shutdown and concurrency correctness tests cover the chosen model.

Anti-patterns

References

• Choosing a construct — read when two models fit or when crossing executor, future, stream or task-group boundaries.
• Concurrency versus parallelism — read when a throughput/latency claim or proposed concurrency increase needs a measurement plan.
• Java 25 ScopedValue
• Java 25 StructuredTaskScope
• Java concurrency API
• JLS 17: Threads and locks
• JEP 444: Virtual Threads
• JEP index