Inside a handler that returns an awaitable, how do you hand a blocking call to a side pool without breaking the framework's contract?

## Why the handler cannot simply call it A blocking call does not stop being blocking because the surrounding handler is awaitable-shaped. Whatever resource is executing the handler at that moment is held for the whole duration of the call, and in an awaitable-handler framework that resource is typically shared by many in-flight requests rather than dedicated to this one. The purpose of offloading is to move the waiting onto a resource you are willing to spend, and to get the framework's resource back immediately. ## The shape that satisfies the contract ```pseudocode handler(request): args = readFrom(request) # cheap, on the calling resource handle = sidePool.submit(() -> blockingCall(args)) return handle .map(result -> response(200, result)) .recover(err -> errorResponse(err)) ``` The rules that shape carries: 1. **Submit, do not call.** The blocking work runs on the side pool, never inline in the handler. 2. **Return the handle.** The handler returns immediately with the submission's handle; the framework subscribes to it and writes the response on completion. 3. **Never wait inside.** Taking the handle and then waiting for its result converts the handler back into a blocking one — now with an extra pool and a context switch for nothing. This is the single most common way an offload is written wrong. 4. **Let the failure be the handle's failure.** If the blocking call throws, that failure must settle the returned handle so the framework's error stage sees it. Catching it and returning a default turns a failure into a success the framework cannot distinguish. ## What does not cross the pool boundary | | stays with the request | needs explicit carrying | |---|---|---| | values read from the request before the hand-off | yes, you captured them | — | | ambient per-request storage the framework populated | no | capture into locals, or use the framework's context-propagation hook | | the framework's error mapping | applies to the returned handle | — | | cancellation when the client goes away | depends on the pool's task model | check explicitly if it matters | Ambient storage — the mechanism frameworks use so that code far from the handler can still reach the current request's identifiers — is the classic casualty. It is usually bound to the executing resource, so a task running on a foreign pool finds it empty or, worse, finds a *different* request's values if the pool's slots are reused without cleanup. Correlation identifiers vanishing from log lines produced inside the offloaded task is the visible symptom. Frameworks differ in whether they propagate such context across a hand-off automatically, offer a hook to do so, or leave it entirely to you; check which before relying on it. ## The pool is part of the contract A side pool must be **bounded** — a pool that grows without limit converts a downstream slowdown into memory exhaustion — and **separate** from any pool the framework uses for its own work, or the isolation you were buying is imaginary. Bounding creates a new outcome the handler must handle: **rejection**, when the pool and its queue are full. That rejection arrives synchronously, at submission, so it takes the *early* error channel rather than the handle's, and it deserves a deliberate response (a busy status with a retry hint is the usual choice) rather than escaping as a generic failure. Separate pools per dependency class are worth the extra objects: one slow dependency saturating a shared pool starves every other offloaded call behind it, which is exactly the coupling offloading was meant to remove. ## What offloading does not buy - It does not reduce the work. The same blocking call takes the same wall time; you have only chosen who waits. - It does not raise the ceiling on the blocking dependency. If it serves twenty concurrent calls, a pool of two hundred just builds a queue in front of it. - It does not help CPU-bound work much. Moving computation off the framework's resource protects responsiveness, but the machine's cores remain the limit. - It does not make the handler simpler. Two error channels now exist — submission rejection and task failure — and both need a mapping. - It does not remove the need to measure. Queue time inside the side pool is invisible in the blocking call's own timing, so instrument submission-to-start separately from start-to-finish; a pool that is quietly saturated looks exactly like a slow dependency otherwise.