Keep asynchronous cURL work in its execution context
This builds on execution contexts in guzzle/promises. When a runtime registers a provider, the default asynchronous cURL handler gives each active fiber or coroutine its own multi handler. A shared client can then serve overlapping requests without one context driving another's transfers.
Without a provider, the existing handler selection and behavior are unchanged. This doesn't require a coroutine extension.
Why this is needed
A client normally keeps one CurlMultiHandler. Calling wait(), tick(), or execute() drives all transfers on that handler, including transfers started elsewhere.
In a long-running worker, a client may be shared through a container or inside an SDK. One request can suspend inside a handler call while another request uses the same client. Besides running work in the wrong request context, overlapping calls on one multi handle can abort the process in coroutine runtimes that hook cURL.
Giving every request a new client avoids sharing that handler, but also loses its connection reuse. This change separates active work while retaining idle handlers and their connections for reuse.
Frameworks need this to work with third-party SDKs, not just HTTP clients they create themselves. Registering the provider before those SDKs create their clients gives clients using Guzzle's default handler the same context isolation and connection reuse, without changes to each SDK. Supporting this in Guzzle removes the need for frameworks to fork or intercept its internals to provide that integration.
Handler ownership and reuse
With a provider configured before client construction, the default asynchronous handler uses ContextualCurlMultiHandler:
- A context borrows a multi handler while it has work. Overlapping contexts use separate handlers.
- Once all transfers finish and handler calls return, the handler goes back into an idle pool. Another context can reuse it while the original context continues doing other work.
- The pool retains up to eight idle handlers by default. The
max_idle_multi_handlersclient option changes that limit; it doesn't limit active contexts or connections. - Setting the limit to zero keeps reuse within each context, but retains no handlers for later contexts.
- Requests made outside managed contexts share one handler.
Synchronous requests keep the existing CurlHandler path, which takes a dedicated easy handle for each request. The leased handlers use the same configured transport-sharing state as the synchronous handler.
A directly constructed CurlMultiHandler also checks ownership when a provider is configured. Another context can't drive it while it has active transfers or a call in progress, including request preparation that may suspend. Misuse throws CrossContextException without changing the handler. Once idle, the handler can be used by another context. Previously queued ticks can't drive work that now belongs to another context.
Framework integration
With the provider from the companion promises PR registered, Hypervel (or another Swoole-based framework) could share one client between coroutines. Inside a running worker with Swoole's cURL hooks enabled:
use GuzzleHttp\Client;
use Swoole\Coroutine;
$client = new Client();
Coroutine::create(static function () use ($client): void {
$response = $client->getAsync('https://example.com/users')->wait();
echo $response->getBody();
});
Coroutine::create(static function () use ($client): void {
$response = $client->getAsync('https://example.com/orders')->wait();
echo $response->getBody();
});
Each coroutine waits on its own request. While their transfers overlap, they use separate multi handlers. Once a handler becomes idle, another coroutine can reuse it and its connections. Swoole handles scheduling; Guzzle keeps each coroutine's transfers and promise callbacks together.
Cleanup
When the runtime finishes a context through the promises API, its unfinished transfers are cancelled before its task queue is drained. Rejection callbacks therefore run inside the context that owns the work. Cleanup continues across cancellation failures and reports the first error.
Weak references avoid keeping ended contexts alive. If a context disappears without being finished, a directly shared handler releases its abandoned native transfers before another context uses it; it doesn't run the abandoned context's promise callbacks.
Configuration and scope
Clients using max_host_connections or max_total_connections keep one multi handler, because those limits apply to that handle. Use such clients from one context at a time; with a provider configured, overlapping use from another context throws CrossContextException. These options can't be combined with max_idle_multi_handlers.
Custom handlers aren't automatically wrapped. Applications can construct ContextualCurlMultiHandler themselves.
The provider must be configured before creating clients. It identifies the current context; it doesn't supply an event loop or make blocking cURL calls nonblocking. The runtime remains responsible for scheduling I/O and finishing contexts.
This raises the guzzlehttp/promises requirement to ^3.2, so it depends on the promises PR being merged and released. Until then, the normal CI dependency installation can't resolve that requirement.
The full test matrix and static checks passed on a temporary validation branch using the companion promises implementation.
Tests cover a client shared by interleaved Fibers, connection reuse before a context ends, pool limits, ownership checks, stale queued ticks, and cancellation during cleanup.
I thought working PRs would be the easiest way to start the discussion. Happy to answer questions and adjust the design based on your feedback.