Add opt-in execution contexts for fibers and coroutines
This adds an opt-in way to keep promise work separate between fibers or coroutines running in the same process. A runtime supplies a provider that identifies the current context. Guzzle then keeps each context's task queue and pending promises with that context.
Without a provider, existing behavior is unchanged. No coroutine extension is required.
Companion: Keep asynchronous cURL work in its execution context. That PR uses this API to let concurrent contexts share a Guzzle client safely.
Why this is needed
Guzzle currently has one task queue for the process. That works when one execution context drives the queue. In a long-running worker, however, one request can suspend while another runs in the same process. When the second request drains the queue, it also runs callbacks queued by the first. Code that reads request-local state can then see the wrong request, tenant, or transaction.
Pending promises have a similar problem. Waiting on or cancelling a promise can drive the work behind it. If another context does that while the original context is suspended, it can interfere with work that's still in progress.
Frameworks need this to work with third-party SDKs, not just HTTP clients they create themselves. Together with the companion Guzzle PR, 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.
The boundary here is the running fiber or coroutine, not the process or the HTTP client.
How it works
Configure an ExecutionContextProviderInterface once at startup, before creating promises. Its current(): ?object method returns an object identifying the running context, or null outside managed contexts. Each live context must have its own object, which stays the same throughout that context and becomes unreachable when it ends. A provider for native PHP Fibers is included:
use GuzzleHttp\Promise\ExecutionContext;
use GuzzleHttp\Promise\FiberExecutionContextProvider;
ExecutionContext::setProvider(new FiberExecutionContextProvider());
With a provider configured:
Utils::queue()uses the current context's queue. Code outside managed contexts continues to use the global queue.- A pending promise belongs to the context that created it. Using it from another context throws
CrossContextExceptionwithout changing the promise. This also covers adopting a promise whose underlying work is still pending. - Settled results can be shared. Callbacks registered through
then()run in the context that registered them, and the returned promise belongs there. Promises created outside managed contexts remain usable from any context, but a suspended wait can't be driven by another context at the same time.
The runtime must drive each context's queue in that context. Registering a callback doesn't resume a suspended context or drain its queue automatically. Likewise, a promise created inside a managed context must be settled there; an external event loop can't settle it from a different context.
Ending a context
The runtime calls ExecutionContext::finish($context) as the last step inside the context, normally from a finally block. Providers can instead implement FinalizingExecutionContextProviderInterface to register that cleanup with the runtime.
Finishing runs registered cleanup callbacks, then drains the task queue, so work that cleanup cancels can still run its rejection callbacks in that context. It continues cleanup after failures and rethrows the first exception afterwards.
Per-context state is kept in weak maps keyed by the context object, and promises hold weak references to their owner. If a context disappears without being finished, its queued callbacks are discarded rather than run in another request. Other contexts can't take over its pending promises. Finishing, explicitly or through a finalizing provider, is still needed to run cleanup.
Framework integration
For example, in Hypervel (or another Swoole-based framework), the integration could look like this:
use GuzzleHttp\Promise\ExecutionContext;
use GuzzleHttp\Promise\FinalizingExecutionContextProviderInterface;
use Swoole\Coroutine;
final class SwooleExecutionContextProvider implements FinalizingExecutionContextProviderInterface
{
public function current(): ?object
{
return Coroutine::getCid() > 0 ? Coroutine::getContext() : null;
}
public function onFinish(callable $finalizer): void
{
Coroutine::defer($finalizer);
}
}
ExecutionContext::setProvider(new SwooleExecutionContextProvider());
The framework registers this once during worker startup, before creating promises or clients. Swoole supplies the context object and runs the registered cleanup when that coroutine ends, so application code doesn't need to call finish() itself.
Compatibility and scope
The package remains compatible with PHP 7.4. Configuring a provider requires PHP 8.0; the included Fiber provider requires PHP 8.1.
The provider identifies contexts. It doesn't schedule Fibers, make blocking I/O nonblocking, or add a dependency on Swoole or another runtime. Frameworks and schedulers supply that integration.
The new execution-context guide covers provider lifetime, queue draining, ownership, and shutdown. Tests cover interleaved contexts, suspended and abandoned waits, callback routing, and cleanup failures.
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.