poolboy checkout returns `{error, timeout}` when pool exhausted

poolboy checkout returns `{error, timeout}` when pool exhausted

Goal: determine the intended semantics of poolboy’s checkout timeout in the context of an exhausted pool, and how to handle this in production code.

Constraints: poolboy 1.5+ no longer emits a distinct `{error, exhausted}`; instead checkout blocks until the supplied timeout expires and then returns `{error, timeout}`. Older releases behaved differently, creating backward‑compatibility ambiguity. Developers often rely on the error type to decide whether to retry, raise an exception, or report a hard failure.

Uncertainty: Is the timeout considered a soft failure that should trigger retry logic, or does it implicitly signal that the pool is saturated and the request should fail immediately?

Questions:

• Does the current poolboy API treat exhaustion as a timeout, or is a separate error type desirable?
• What is the recommended pattern for distinguishing a genuine timeout from a pool‑exhaustion scenario?
• How should code be written to maintain compatibility across poolboy 1.4 and 1.5+?