Concurrent Collections And Synchronizers

Concurrent Collections and Synchronizers

Purpose

Once "use a concurrent collection", "use a queue" or "use a limit" is the decision, this is the next one: which member of the family, with which parameter, and what breaks when it is wrong. These failures are rarely exceptions — a consumer that idles with work queued, a limit of 8 that admits 12, a latch nobody counts down, a heap dump full of queue nodes. The rule that a thread-safe collection does not make a sequence atomic belongs to java-thread-safety-contracts; the mechanism it implies is here. Baseline Java 25; vendor support status and version-sensitive claims must be checked separately.

Before applying that authoring baseline, inspect the target compiler release/toolchain, deployed JDK/vendor/build and existing dependencies. Do not upgrade or enable preview merely to apply this skill. StructuredTaskScope is preview in Java 25; route to structured-concurrency for its version-specific API and compiler/runtime flags, and use existing stable coordination APIs when preview is not authorized.

Workflow

1. Name the admission policy before choosing an implementation. If overload can occur, state the capacity or explain why an intrinsically unbounded structure is safe and bounded elsewhere.
2. Pick the member from the tables below and write down the cost accepted. A choice with no stated cost was not made.
3. Pick the exact method form. offer(e, timeout, unit) not add; while not if; awaitNanos(remaining) not the original timeout. The form is where the correctness is.
4. Make cleanup exception-safe. For owned locks/permits, acquire immediately before try and release in finally only after successful acquisition. Latches and phasers need their own party accounting rather than a mechanical lock template.
5. Verify with the section below, not by re-reading the code; these failures are silent.

Selecting a queue

Start with the required bound, ordering and handoff semantics; ArrayBlockingQueue(n) and LinkedBlockingQueue(n) are common bounded choices, not universal defaults. Mechanism, symptom chains and code: references/queues.md.

Selecting a coordinator

Failure modes and worked code: references/synchronizers-and-conditions.md.

Replacing a compound action on a ConcurrentHashMap

Leaving the compound form in place produces duplicate initialisation — two connections, two schedulers, a doubled counter — invisible in tests and load-dependent in production.

Rules

• Prefer an explicit finite capacity where the queue is the admission boundary — no-arg LinkedBlockingQueue uses Integer.MAX_VALUE. Structures without a useful finite capacity do not provide overload control; remainingCapacity() is contract data, not proof of safety.
• A timed offer fits request paths that must bound admission delay and handle false; it is not automatically a 503 or spill policy. put(e) fits deliberate producer throttling; offer(e) fits designed and counted drop/retry. add(e) is rarely useful in a producer loop because it makes a capacity condition an IllegalStateException("Queue full") and on an unbounded queue can never fire. An offer whose boolean is discarded is silent data loss.
• Concurrent size() is monitoring information, not admission control. if (map.size() < LIMIT) map.put(…) is a race. Use mappingCount() when an approximate long count is appropriate. Avoid hot-path or high-frequency scrape calls to size() on ConcurrentLinkedQueue or LinkedTransferQueue because it traverses.
• OpenJDK bug JDK-8371740 reports LinkedTransferQueue.poll() returning null despite a non-empty queue in releases 21–25, fixed in 26. Check the deployed build/backports before relying on the fix; do not use queue emptiness as a durable completion protocol.
• compute* and merge may block some updates while the function executes. Keep it short and do not modify the map from the function, as required by the API. Current OpenJDK uses per-bin coordination, but application correctness must not depend on its exact monitor layout. For a loader that can block, use the failure-evicting memoiser in references/collections.md.
• IllegalStateException("Recursive update") is only required for a detectable recursive update that would otherwise not complete. It is not an enforcement boundary. Any map mutation from a remapping function violates the API constraint even when a particular build does not throw.
• Distinguish two iterator contracts. Weakly consistent (CHM, skip lists, ConcurrentLinkedQueue) never throws ConcurrentModificationException and may reflect later writes; snapshot (copy-on-write) captures a consistent sequence of element references at creation, but not a deep snapshot of mutable element state. It ignores later list changes; a listener registered during dispatch waits for a later traversal, and iterator mutation throws.
• Copy-on-write cost is writeRate × size, not the read:write ratio. Use it for configuration-shaped state whose write rate is bounded by human or control-plane action, never for request-scoped data; batch with addAll. CopyOnWriteArraySet.contains is a linear scan.
• For locks and permits, acquire immediately before try and release in finally; put no throwing work between them. A missing countDown() can park a waiter indefinitely; a missing release() erodes capacity; a leaked unlock() is permanent, because a ReentrantLock is not released when its holder dies.
• The untimed tryAcquire() and tryLock() ignore the fairness setting and barge; tryAcquire(0, unit) honours it and also detects interruption. Whether the limit should be fair at all is a sizing decision — concurrency-limiting-and-bulkheads.
• Wait on a Condition in a while testing the predicate, never an if. Spurious wakeups are only one of the three reasons, and not the one that makes if unconditionally wrong. Symptom: a negative count or an item consumed twice, under load only.
• signal() is appropriate only when every waiter on that condition uses a compatible predicate and progress is preserved if the selected waiter cannot proceed; otherwise consider separate conditions or signalAll(). A wrong selection can leave an eligible waiter parked — one thread parked forever while everything else runs, and the dump looks like ordinary parking.
• In a re-wait loop carry the remaining time: nanosRemaining = cond.awaitNanos(nanosRemaining). Re-passing the original turns N wakeups into N × timeout — a "5-second timeout" that occasionally takes minutes and never reports one. await(t, unit) returns false but no remaining time.
• Choose ReentrantLock over synchronized on capability: timed and interruptible acquisition, tryLock, fairness, non-block-structured locking, more than one condition queue. Pinning has not been a reason since JEP 491 (JDK 24) — virtual-threads-internals owns that diagnosis.
• A read-only ReentrantReadWriteLock holder cannot upgrade while retaining its read hold: blocking acquisition may wait indefinitely, whereas tryLock can fail or time out. A thread already owning the write lock may reenter it. Standard deadlock detection may miss read-hold stalls; inspect stacks and ownership. Downgrade is legal; readLock().newCondition() throws. The reader cap is 65535 on JDK 21 and Integer.MAX_VALUE on JDK 25; measure against a plain lock before adding an RRWL.
• StampedLock is not reentrant, has no ownership and no fairness policy. Re-entry through a callback, listener or guarded object's method can self-deadlock and is not represented as an ownable-lock cycle. An optimistic read must not act on a potentially inconsistent snapshot before successful validation; copy only safe fields into locals, validate, then use them.
• Reach for AbstractQueuedSynchronizer last: BlockingQueue → Semaphore → latch/barrier/phaser → ReentrantLock + one Condition per predicate → StructuredTaskScope → atomics. Only a blocking synchronizer with a novel acquisition predicate justifies it.

Verification

• jcstress for the substitution table. Two @Actors racing containsKey+put against putIfAbsent on one key, an @Arbiter reading the result, the interleaved outcome FORBIDDEN; run both shapes and record observed outcomes; a finite run need not expose every race. Bounded liveness tests and jcstress termination tests can expose hangs; a stale outcome is evidence of non-termination under that test, not proof of a particular lost signal.
• Invariant checks in tests and diagnostics: fixed-limit semaphores should never exceed their configured permit count; queue construction should expose its admission policy; non-reentrant designs should test callback/re-entry. Java assertions are disabled unless enabled and cannot be the production enforcement mechanism.
• Review queue construction against the admission policy — flag effectively unbounded queues and require an explicit external bound or workload argument. Encode that repository policy in a gate where useful; remainingCapacity() alone does not prove absence of a bound. The executor factories that hide queues are executors-and-task-lifecycle's; how to write the rule is architecture-testing's.
• JFR with an explicit recording configuration. AQS-based waits commonly surface through park events, while monitor contention has monitor events. Event enablement and thresholds vary by JDK and recording template; inspect the active settings before treating absence as evidence.
• Metrics with the right shape: bounded queue depth as a fraction of capacity plus a counter of offer rejections (the rejection is the signal, depth is not); enqueue-to-dequeue latency timestamped on the item; availablePermits() alerted on a trend. getQueueLength() is a lock method — threads waiting to acquire, not queue depth — documented as monitoring only. A startup deployment build/backport status recorded when the LinkedTransferQueue.poll() issue is relevant.

References

• Concurrent collections — the bin lock, which recursions are detected and which are silent, the failure-evicting memoiser, keySet variants, bulk ops, the wrapper decision, copy-on-write, skip lists. Read before putting anything inside a compute* function, and when choosing between CHM, a synchronized wrapper, copy-on-write and a skip list.
• Blocking queues — the four insert/remove/examine forms, the implementation comparison, the unbounded-queue failure chain, drainTo batching, the LinkedTransferQueue bug, DelayQueue, poison pills. Read when adding, sizing or replacing a queue.
• Synchronizers and conditions — latch, barrier, phaser, semaphore and exchanger failure modes, the permit-leak and over-release shapes, the Condition protocol and a correct bounded buffer. Read when threads must coordinate.
• Explicit locks — the capability table against synchronized, the JEP 491 reframing, the tryLock recipe, RRWL upgrade/downgrade and the reader-cap change, StampedLock with the canonical optimistic read, when AQS is justified. Read when a lock is chosen or blamed.
• Java 25 concurrent collections and synchronizers
• Java 25 lock package
• OpenJDK JDK-8371740: LinkedTransferQueue.poll() issue