Limit pending connection queue size

[chornyi]

When connections are unavailable, HIkariCP queues connections (in pending state) until they timeout. Is there a way to limit this queue size? Or is this considered unnecessary if connectionTimeout is set low enough?

[brettwooldridge]

The pending queue itself is unbounded, yet what is being enqueued is threads, so there is a natural OS imposed limit on how large that collection could potentially be. There is certainly no risk of an out-of-memory error.

I wouldn't waste much effort trying to control the size of the collection with the connectionTimeout. Instead you should be focused on what level of responsiveness you application needs, and tuning the timeout toward that goal.

[vlsi]

Hi @brettwooldridge — I understand the position that connectionTimeout bounds waiting time, but I’m not convinced it’s sufficient as the only robustness control for all apps.

connectionTimeout is a time bound, not a load bound: under spikes, threads can accumulate unboundedly waiting for the pool (stack/memory + context switching), and then fail in a thundering herd after ~timeout. This can amplify outages even when the DB/pool recovers quickly.

Tuning is also tricky: a low timeout (e.g. <100ms) improves overload latency but can produce “false” timeouts during STW GC/safepoint pauses or scheduling hiccups; a high timeout (e.g. 5s) avoids those but adds multi-second tail latency and increases the waiter buildup.

Would you consider re-evaluating whether a bounded wait queue / max waiters (or an explicit “fail-fast when exhausted” mode) should be available? Even if off by default, it would allow a hard safety boundary without relying entirely on timeout tuning. Alternatively, could the docs recommend upstream admission-control patterns (bulkheads/semaphores) to help operators reason about this?

Happy to provide concrete reproduction scenarios / measurements if that helps.

[vlsi]

I've prepared a draft PR that shows what I mean: #2387
It would be great if you could clarify if that is something that could be accepted.