PHP True Async RFC Stage 4 View as Markdown

Hello.

Just a quick question - other methods that tried to provide async/parallel type functionality previously were only available via the CLI.

TrueAsync itself is integrated into PHP in such a way that it is
always active. The scenario you described is technically possible (Of
course, this can also be useful for sending telemetry in a way that
doesn’t interfere with request processing.), but it’s not particularly
relevant in the context of modern development.

Why?

Because client requests are usually processed sequentially, step by
step. Parallel tasks are rare.

This is simply not true. The example you're replying to is quite common.

It's even more common for the database. WordPress, Drupal, and many other such systems frequently run different DB queries to build different components of a page. (Blocks, widgets, components, the names differ.) Being able to do those in parallel is a natural optimization that we were thinking about in Drupal nearly 15 years ago, but it wasn't viable at the time.

Therefore, from the server’s
perspective, the main benefit of concurrency is the ability to handle
multiple requests within a single process.

That is A benefit. It is not the only benefit. Being able to compress the time of each request in a shared-nothing model is absolutely valuable.

Remember, in the wild, PHP-FPM and mod_php are by orders of magnitude the most common ways PHP is executed. React, Swoole, etc. are rounding errors in most of the market. And the alternate runtime with the most momentum is FrankenPHP, which reuses processes but is still "one request in a process at a time."

The same thing that Swoole,
AMPHP, and other modern backend solutions do.

And this is one of the reasons why FPM is morally outdated and

I am going to assume this is a translation issue, because "morally outdated" is the wrong term here. "Morally outdated" is how you'd describe "racial segregation is good, actually." Not "this technology is slower than we need it to be." You probably mean "severely outdated" or something along those lines.

Which, as I explained above, is simply not true. PHP is going to be running in a mostly shared-nothing environment for the foreseeable future. Those use cases still would benefit from async support.

--Larry Garfield

Hello.

Why doesn’t scope implement Awaitable?

Let’s say there’s a programmer named John who is writing a library,
and he has a function that calls an external handler.
Programmer Robert wrote the externalHandler.

function processData(string $url, callable $externalHandler): void
{
   ...
    $externalHandler($result);
}

John knows which contracts are inside processData, but he knows
nothing about $externalHandler.
From the perspective of processData, $externalHandler acts as a
black box.
If John uses await() on that black box, it may lead to an infinite wait.

There are two solutions to this problem:

1. Delegate full responsibility for the program’s behavior to
   Robert, meaning to $externalHandler
2. Establish a limiting contract

Therefore, if a Scope needs to be awaited, it can only be done
together with a cancellation token.

In real-world scenarios, awaiting a Scope during normal execution
makes no sense, because you have a cancellation policy.
This means that at any necessary moment you can dispose() the Scope
and thus interrupt the execution of tasks inside the black box.

For the TaskGroup pattern, which exists in the third version of the
RFC, awaiting is a relatively safe operation, because in this case we
assume that the code is written by someone who has direct access to
the agreements and bears full responsibility for any errors.

So, Scope is intended for components where responsibility is shared
between different programmers, while TaskGroup should be used when
working with a clearly defined set of coroutines.

I don’t get it. What does different programmers working on a program have to do with whether or not scopes implements Awaitable? Scope has an await method, it should be Awaitable. await() takes a cancellation and thus anything Awaitable can be cancelled at any time. I don’t see why scope is special in that regard.

If John uses await() on that black box, it may lead to an infinite wait.

This is true of any software or code. Knowing whether or not something will ever complete is called The Halting Problem. It is unsolvable, in the general sense. You can await() a read of an infinite file, or a remote file that will take 5y to read because it is being read at 1 bps. Your clock can fry on your motherboard, preventing timeouts from ever firing. Your disk can die mid-read, preventing it from ever sending you any data. There is so much that can go wrong. To say that something that has an await method isn’t Awaitable because it may never return is true for ALL Awaitable tasks as well. It isn’t special.

— Rob

Hello.

I think you should allow for a lengthier review period so that people will have enough time to contribute their thoughts and ideas,
to make sure all unclarities are cleared up, and so, to have a better chance of being accepted.

I’m happy to allow as much time as needed. How about we extend the
review period by another two weeks?

Thank you, Ed

When I await(), do I need to do it in a loop, or just once?

It depends on what is being awaited.
On one hand, it would probably be convenient to have many different
operations for different cases, but then we make the language
semantics more complex.

Coroutines become Future that only await once, while Signal is something that can be awaited many times.
At the moment, only such objects exist. It’s hard to say whether there
will be others.
Although one can imagine an Interval object, there are some doubts
about whether such an object should be used in a while await loop,
because from a performance standpoint, it’s not very efficient.

It might be good to clarify this when we talk about the Awaitable Interface then? Maybe something like:

"In PHP 8.6 the only awaitables are single-completion. Future versions may add multi-event awaitables." just to clear it up for early adopters?

But the example setChildScopeExceptionHandler does exactly this!
The Scope-level handler does not interfere with coroutine completion.
And it is not called because the cancellation exception is "absorbed"
by the coroutine.

:thumbsup:

Further, much framework/app code uses the $previous to wrap exceptions as they bubble up,

If a programmer wants to wrap an exception in their own one let them.
No one forbids catching exceptions; they just shouldn’t be suppressed.

Async\isCancellation(Throwable): bool
Why make a separate function if you can just walk through the chain?

If everyone writes their own isCancellation() we risk divergence (not to mention, it will be faster in C and basically need to be checked on every catch that might await); having one blessed function guarantees consistent detection and can allow for static-analysis support.

Minor nit: in the Async\protect section, it would be nice to say that cancellations being AFTER the protect() are guaranteed, and also specify reentry/nesting of protect(). Like what happens here:

That’s a good case! Re-entering protect should be forbidden that must
not be allowed.

<3 that's good to know! It definately needs to be in the RFC. If you don't mind me asking: why is this the case?

Also, if I'm reading this correctly, a coroutine can mark itself as canceled, yet run to completion; however anyone await()'ing it, will get a CancellationException instead of the completed value?
If a coroutine is canceled, its return value will be ignored.
However, of course, it can still call return, and that will work
without any issues.
I considered issuing a warning for such behavior but later removed it,
since I don’t see it as particularly dangerous.
This point requires attention, because there’s a certain “flexibility”
here that can be confusing. However, the risk in this case is low.

I would find it surprising behaviour -- if you cancel a context in go, it may or may not complete, but you get back both the completion (if it completed) and/or the error. In C#, it throws an exception and it never completes. Languages have different ways to do it, but it should be documented in the RFC what the behaviour is and how to handle this case. Ergonomics matter as much as the feature existing.

As far as observability goes, it might be a good idea to issue a notice instead of a warning. Notice is often suppressed and rarely causes any issues, but in development, seeing that would at least let me know something was going on that I should investigate.

Allowing destructors to spawn feels extremely dangerous to me (but powerful). These typically -- but not always -- run between the return statement and the next line (typically best to visualize that > as the "}" since it runs in the original scope IIRC). That could make it 'feel like' methods/functions are hanging or never returning if a library abuses this by suspending or awaiting something.

Launching coroutines in destructors is indeed a relatively dangerous
operation, but for different reasons mainly related to who owns such
coroutines. However, I didn’t quite understand what danger you were
referring to?

Asynchronous operations, as well as coroutine launching, are indeed
used in practice. The code executes properly, so I don’t quite see
what risks there could be, apart from potential resource leaks caused
by faulty coroutines.

I think we missed each other here. Consider the following code:

function test() {
$r = new AsyncResource();
return 42; // destructor suspends here
}

Would this delay the caller's return until the destructor's coroutine finished, or is it detached? If detached, can it interleave safely with subsequent code? This should be documented in the RFC so people can plan for it and use it appropriately (such as managing transactions or locks inside destructors).

async.zombie_coroutine_timeout says 2 seconds in the text, but 5 seconds in the php.ini section.
Thanks.

What is defined as "application considered finished?" FrankenPHP workers, for instance, don’t "finish" — is there a way to reap zombies manually?

The Scheduler keeps track of the number of coroutines being executed.
When the number of active coroutines reaches zero, the Scheduler stops
execution. Zombie coroutines are not counted among those that keep the
execution running. If PHP is running in worker mode, then the worker
code must correctly keep the execution active. But even workers
sometimes need to shutdown.

I have some workers that haven't restarted since April. :) So, having a way to manually reap zombies (much like we do with OS-level code when running as PID 1) and track them, would be nice to have. At least, as part of the scheduler API.

it would be good to specify ordering and finally/onFinally execution here
Doesn’t the RFC define the order of onFinally handler execution?
onFinally handlers are executed after the coroutine or the Scope has completed.
onFinally is not directly related to dispose() in any way.

When dispose() is called, coroutine cancellation begins. This process
may take some time. Only after the last coroutine has stopped will
onFinally be invoked. In other words, you should not attempt to link
the calls of these methods in any way.

This should be documented on the RFC, it still doesn't explain what the order of operations is though. This matters because if you are doing cleanup during disposal, you need to know what things will still be around (for reference, order of operations for GC is well documented and defined https://www.php.net/manual/en/features.gc.collecting-cycles.php which is what I'm expecting to see here).

Maybe something like Async\isEnabled() to know whether I should use fibers or not.
Good idea!,
considering that such a function actually exists at the C code level.

Is this "same exception" mean this literally, or is it a clone? If it is the same, what prevents another code path from mutating the original exception before it gets to me?
It’s the exact same object that is, a reference to the same instance.
So if someone modifies it, those changes will, of course, take effect.

This should probably be documented in the RFC: "Exceptions and returned objects are shared objects; mutating them is undefined behavior if there are multiple awaiters."

Is there also a timeout on Phase 1 shutdown? Otherwise, if it is only an exception, then this could hang forever.

That’s true! A hang is indeed possible. I’m still not sure whether
it’s worth adding an auxiliary mechanism to handle such cases, because
that would effectively make PHP “smarter” than the programmer. I
believe that a language should not try to be smarter than the
programmer if the application runs in a certain way, then it’s
probably meant to be that way.

I think of it more as observability than smarts (esp if the timeout is configurable) ... otherwise, how would you even know if it is hanging on shutdown vs. doesn't even know it is supposed to be shutting down? I'm reminded of certain CLI tools that require me issuing a SIGTSTP (ctrl-z) to issue a SIGTERM or SIGKILL because SIGINT (ctrl-c) doesn't appear to work. If it is my program, is it that there is a bug with SIGINT handlers -- or is it hanging during shutdown? Having a timeout there would at least protect me from my customers/users getting stuck due to a bug, and I could always set the timeout to something infinite-ish (0? -1?) if that is the behaviour I want.

— Rob

This seems a bit contradictory and confuses things. When I await(), do I need to do it in a loop, or just once?
It might be a good idea to make a couple subtypes: Signal and Future. Coroutines become Future that only await once, while Signal is something that can be awaited many times.

I made a mistake in my previous response, and it requires clarification.
Classes that can be awaited multiple times are indeed possible.
These include TimeInterval, Channel, FileSystemEvent, as well as
I/O triggers.

All of these classes can be Awaitable.
This is done to allow bulk waiting on objects, regardless of how they
work internally.
So this is meant for functions like awaitXX, although such behavior
is also possible for the await() function itself:

$timeInterval = new Async\TimeInterval(1000);
while(true) {
   await($timeInterval);
}

As for objects of type Future, it’s clear that in future RFCs there
will be a FutureInterface, which will be implemented by coroutines.

Hi Edmond,

I've been meaning to review your RFC and implementation for some time, but for various reasons, I still haven't been able to give it a thorough read and review.

I noticed this portion of the discussion and wanted to drop a note now, rather than waiting until I was able to read the entire RFC.

Awaitables should always represent a single value. Awaiting multiple times should never result in a different value.

Async sets of values should use a different abstraction to represent a set. rxjs Observables (rxjs.dev) are on example. AMPHP has a pipeline library, https://github.com/amphp/pipeline, which defines a ConcurrentIterator interface. The latter IMO is more appropriate for PHP + fibers. I recommend having a look at how Future and ConcurrentIterator are used within AMPHP libraries.

I think you should consider additional time beyond only two more weeks for discussion of this RFC before bringing it to a vote. PHP 8.6 or 9 is some time away. This is definitely not an RFC to rush to voting.

Cheers,
Aaron Piotrowski

This seems a bit contradictory and confuses things. When I await(), do I need to do it in a loop, or just once?
It might be a good idea to make a couple subtypes: Signal and Future. Coroutines become Future that only await once, while Signal is something that can be awaited many times.

I made a mistake in my previous response, and it requires clarification.
Classes that can be awaited multiple times are indeed possible.
These include TimeInterval, Channel, FileSystemEvent, as well as
I/O triggers.

All of these classes can be Awaitable.
This is done to allow bulk waiting on objects, regardless of how they
work internally.
So this is meant for functions like awaitXX, although such behavior
is also possible for the await() function itself:

$timeInterval = new Async\TimeInterval(1000);
while(true) {
   await($timeInterval);
}

As for objects of type Future, it’s clear that in future RFCs there
will be a FutureInterface, which will be implemented by coroutines.

Hi Edmond,

I've been meaning to review your RFC and implementation for some time, but for various reasons, I still haven't been able to give it a thorough read and review.

I noticed this portion of the discussion and wanted to drop a note now, rather than waiting until I was able to read the entire RFC.

Awaitables should always represent a single value. Awaiting multiple times should never result in a different value.

Async sets of values should use a different abstraction to represent a set. rxjs Observables (rxjs.dev) are on example. AMPHP has a pipeline library, https://github.com/amphp/pipeline, which defines a ConcurrentIterator interface. The latter IMO is more appropriate for PHP + fibers. I recommend having a look at how Future and ConcurrentIterator are used within AMPHP libraries.

I think you should consider additional time beyond only two more weeks for discussion of this RFC before bringing it to a vote. PHP 8.6 or 9 is some time away. This is definitely not an RFC to rush to voting.

Cheers,
Aaron Piotrowski

• The glossary in "Overview" is good, but probably incomplete. The
  examples there, with no description, do not help much and could be
  removed, imo.

Do I understand correctly that I should remove the examples without
descriptions?

Examples in the Overview section aren't very helpful. I would remove
them from there, but maybe some of them need to appear later. I didn't
read it that carefully to suggest precise changes.

Or would it be better to add descriptions to them?
Although the last examples might not be very illustrative or easy to grasp.

the "Scheduler and Reactor" section does not explain much over what's in the glossary.

What else do you think could be added?
The internal implementation doesn’t belong in the scope of the RFC, it
can change.
They don’t have any special API in the PHP userland.
The reactor can only be used directly at the C/C++ level, meaning
within a PHP extension.
It’s also intentionally impossible to directly affect the Scheduler’s behavior.

I think that it might be better to not mention them at all in the RFC.
Or better separate parts that describe userland and engine. The
structure of the Proposal is a bit chaotic.

--
Aleksander Machniak
Kolab Groupware Developer [https://kolab.org]
Roundcube Webmail Developer [https://roundcube.net]

PGP: 19359DC1 # Blog: https://kolabian.wordpress.com

On Mon, Oct 27, 2025 at 6:05 PM Larry Garfield larry@garfieldtech.com
wrote:

Hello all.

Current work and discussion plan for this RFC

1. By the end of this week, the proposed changes at

https://github.com/true-async/php-true-async-rfc/issues
will be accepted if no objections are raised.

2. After that, the RFC document will be updated, and a new 2-week
   discussion period will begin.

3. After the new changes are accepted, the RFC will be updated again,
   and the process will repeat.

The discussion will be extended as long as necessary, including at the
request of the participants.

---

With best regards,
Ed

I am not sure how feasible this is, but would there be a way to split the
"async toggle" of IO operations off to its own PR/RFC? To me, that is by
far the most important part of this RFC as that's the biggest blocker for
wider async adoption, but I'm not sure how many layers are needed above it
to make it possible to toggle in a safe fashion.

Hi!

Can you clarify what you mean by "async toggle"?
Is it the actual implementation that would use async constructs if the
current context is a coroutine for each implementation of IO functions?
Yes, for that, it would be nice to have separate PRs, even multiple ones
for easier review. But maybe you mean something else...

--
Alex

Hello

I am not sure how feasible this is, but would there be a way to split the "async toggle" of IO operations off to its own PR/RFC?
To me, that is by far the most important part of this RFC as that's the biggest blocker for wider async adoption,
but I'm not sure how many layers are needed above it to make it possible to toggle in a safe fashion.

Why is this considered the main blocker? (Or maybe I didn’t quite
catch the meaning.)
After all, this is precisely the part of the RFC that doesn’t actually
change the behavior from the user’s perspective inside a coroutine.

As for the PRs. There’s no doubt there will be several. I hope the PHP
core team will help with the code separation process and advise on the
best way to do it, since it’s not a trivial task.

As for the toggle switch. If a developer doesn’t use spawn, then why
toggle anything at all?
And even if they do, there’s still no difference — the code won’t
start executing “differently.”

Best Regards, Ed

I am not sure how feasible this is, but would there be a way to split the "async toggle" of IO operations off to its own PR/RFC?
To me, that is by far the most important part of this RFC as that's the biggest blocker for wider async adoption,
but I'm not sure how many layers are needed above it to make it possible to toggle in a safe fashion.

Ah, I think I understand what you mean.
Yes, from an implementation standpoint, non-blocking behavior is
provided by the Scheduler API and Reactor API. These two APIs are
always available anywhere — in the core, extensions, and so on.

However, this isn’t part of the RFC itself, as it belongs to
implementation details. Moreover, do you remember the first version of
the RFC? It had a function that explicitly started the Scheduler. So
indeed, in that first version PHP could be in two states: synchronous
and asynchronous.

What’s the difference in this RFC?
PHP is always in an asynchronous state. Even when executing
index.php, you can think of it as running inside a coroutine. There’s
just a single coroutine, so no switching occurs (although an extension
could, for example, create another coroutine — which is perfectly
valid).

You keep writing your code exactly as before. You don’t need to think
about PHP being “asynchronous” now. As long as you’re writing code
inside a single coroutine, you’re still writing synchronous code.

-- Ed

PUML Link here:

https://editor.plantuml.com/uml/TLBDRjGm4BxFKunw0QJTvSu1LQfQgH9L4HLmTftPpQYE7SrCkXigtXqx8MxOYfF7zZVVZyUNQaviw0Be4yVUYUimS2GRUy97-iKa0COM2B-HyvPasmW_KyIh96cm3CMxr5004FBcuY4ZBwvFvFDTAgXeT39yVyEF91ykq6azUm74LLCbd41r1x__eNxmBJL389bGTOSlPxZPxOpwMvyBNkSOXbzIwWjgAWh9Exm9wOXfZxJ4WDUms-tdolS9tT6nuUt7UwH21ijDHbLl1HUJyNv48TUCw6kqIlkcOMGA3QQ8aKusom1a5aBXGsl5NOL3hJ9rD4b1NpKmy9xyw0FjuDPG1-qfDYk05fKvXuiD2kdGaOArrE6nfLZJ2lL9JASGfKztGBcXc3gpjamOtlw3DeKi_kCErPpH1lBYdpQJyjNNxoXqO3KItQtUPXu3AHxPMex8zb_bnMmTH9SYvrLnpu6m8VN2VJdOW76NXMPjvKDqGV6P7Tu_xE1d2UxYF5LCtWy5oJOFacdryrPUBdCrTE4F