PHP True Async RFC Stage 5

Hi Edmond!

Hi

1.5 RFC:
https://wiki.php.net/rfc/true_async

Here’s the fifth version of the RFC with the updates made after the
1.4 discussion.

Starting from 2025-11-03, there will be a two-week discussion period.

Changelog:

• Added FutureLike interface methods: cancel(), isCompleted(),
  isCancelled()
• Renamed Coroutine::isFinished() to Coroutine::isCompleted()
• Clarified exit/die behavior: always triggers Graceful Shutdown mode
  regardless of where called
• Added rationale for “Cancellable by design” policy: explains why
  default cancellability reduces code complexity for read-heavy PHP
  workloads
• RFC structure improvements: reorganized Cancellation section with
  proper subsections hierarchy
• Moved “Coroutine lifetime” as subsection under Coroutine section
• Extended glossary with Awaitable, Suspension, Graceful Shutdown, and
  Deadlock terms
• Introduced FutureLike interface with single-assignment semantics and
  changed await() signature to accept FutureLike instead of Awaitable
  for type safety
• Split RFC: Moved Scope and structured concurrency functionality to
  separate Scope RFC. Base RFC now focuses on core async primitives
  (coroutines, await, cancellation)

I decided not to wait until Monday and made the changes today. If
anyone has read version 1.4 and has comments on it, they’re still
relevant.

The Scope API has been moved to a separate RFC:
https://wiki.php.net/rfc/true_async_scope

---

Best Regards, Ed

Thanks for the RFC update! I've been trying to read and understand this RFC
since its earlier versions and I can definitely feel it getting easier to
digest, which I can only assume it's a good thing for RFC voters - it's
easier to vote No because something is too complex / too hard to understand.

One minor question: is this section
https://wiki.php.net/rfc/true_async#awaiting_a_result_with_cancellation
named wrongly? I'm not sure how this snippet of code relates to
cancellation.

Onto more important things. In regards to the change of Awaitable vs
FutureLike, my understanding of the discussion is that on the
implementation side it was asked about whether an Awaitable object should
be awaited in a loop (consumed until completion) or if it should be awaited
only once, which also raised the question about idempotency and whether an
object is awaitable more than once. While the change makes the type-system
somewhat more explicit in regards to how await() is meant for a single-shot
Awaitable object (named FutureLike), it does mean the implementation of
things like awaitAll(Awaitable[] $awaitables) is no longer a simple loop to
await every item in the array.

My questions are:

• What's the difference between Multishot Awaitables and Generators?
• If await() is hardened to FutureLike only, doesn't this mean that
  multishot awaitables are not really capable of being awaited anymore?
  Doesn't this mean that the Awaitable interface becomes out-of-sync with the
  await() function and it stops making sense?
• Shouldn't FutureLike be Awaitable and what has been described as
  Multishot awaitables should actually be generators / array of / list of
  Awaitables?

In regards to Cancellable by Design. In the current state of PHP, we can
assume that if a function used to throw an Exception and a future version
stops throwing said exception it is not considered a BC Break. Of course,
throwing a different exception not part of the hierarchy is a BC break.
But when an exception signals "I cannot handle this" and a future version
becomes capable of handling it, that in essence is a feature/enhancement
and not treated as a BC break. With "Cancellation by Design" we are
expected that every coroutine be cancellable and that we must write try /
catch to design for cancellation. This seems to open up a different
development flow where catch blocks can be fundamentally part of the BC
promise. One possible alternative would be e.g. await(Awaitable $awaitable,
Closure $cancellation) where the cancellation of a coroutine would trigger
the specified Closure. Now, I don't want to dive too much into the
trade-offs of these options, what I want is to spark the idea that there
may be multiple ways to design cancellable coroutines. When I consider
that, plus the added fact that the RFC is very dense, extensive and hard to
digest, wouldn't it be best to postpone coroutine cancellations altogether?
The RFC itself states:

[...] read operations (database queries, API calls, file reads) are
typically as frequent as—or even more frequent than—write operations. Since
read operations generally don't modify state, they're inherently safe to
cancel without risking data corruption.

which not only I agree with, but also want us to focus on this very fact.
What if the first version of Async PHP provides userland with the ability
to trigger coroutines for reading purposes only? We will not forbid/prevent
anybody from shooting themselves if they want to, but we can still clearly
state the design principle that Async PHP is meant to spawn coroutines
cancellable by design. There will not be any coroutine markers in the
future nor there will be assumptions that coroutines written for the 1st
version of Async PHP must not be cancellable. The assumption is that the
first version of Async PHP should be treated as a way to perform read
operations only and a future RFC / enhancement will bring cancellation
capabilities (be it Closure, Try / Catch, what have you). My reasoning is
that this would further reduce the scope of the RFC while still introducing
real life useful async components to PHP, even if at a limited capacity. It
gives voters less concepts to understand, digest, agree on and approve and
it extends the opportunity to focus on specific deep aspects of Async PHP
in chunks and throughout different stages.

--
Marco Deleu

Hi Edmond,

Am 30.10.25 um 9:19 AM schrieb Edmond Dantes:

Hi

1.5 RFC:
https://wiki.php.net/rfc/true_async

first of all thank you for investing so much time and effort into
improving PHP.

The True Async RFC changed a lot in the past iterations and removed a
lot of related but tangential topics. I really appreciate your
willingness to adapt to get the best possible outcome.

What I now see is as far as I understand essentially a Fiber 2.0 RFC so
I wonder if it would not be better to improve the available Fibers
instead of creating an incompatible second mechanism.

The Coroutine class is essentially a Fiber class that can be cancelled
and restricted by a cancellation awaitable.
The Fiber class could get startWithTimeout($timeout, ...$args) and
resumeWithTimeout($timeout, mixed $value = null) methods as well as a
cancel() method.
It wouldn't be a Fiber in the pure compsci way any more but I am willing
to accept that if it prevents us from having two ways for (semi)
cooperative multitasking.

The part about how the Awaitable and FutureLike interfaces work is very
unclear to me. They are there but they do not describe how they could be
used in a truly multitasking fashion. That is somehow open to the
Scheduler/Reactor which are not described to reduce the complexity.
The RFC as it is allows to await(new Coroutine()) which is syntactical
sugar for $fiber = new Fiber(); $fiber->start(); while (!$fiber->isTerminated()) $fiber->resume(); So a followup RFC would
need introduce this additional mechanism into these interfaces.

Also I do not really understand why the "cancellation" is an awaitable.
If the provided awaitable is itself some infinitely blocking Coroutine
(e.g. while (true) {}), how can the scheduler run the actual Coroutine
and the "cancellation" awaitable to determine whether the Coroutine
should be cancelled or not? As long as there is no multithreading, this
does not make sense for me.

In addition, what happens if a Coroutine is suspended and is restarted
again. Is the cancellation awaitable restarted? Or just continued?

I am really skeptical if the current RFC is the right way to go,
establishing a Coroutine and Awaitable and FutureLike interfaces in
competition to the existing Fiber.

I would rather see a step-by-step plan with gradual improvements like this:

1. Propose some changes to Fiber so it can be interrupted after a timer
   expired and it can be cancelled.

2. Add a unified polling mechanism for all kinds of IO events (timeouts
   and signals included) like Jakub's "Polling API".

3. Enhance the Fiber class so it can expose a PollHandle/Pollable that
   it is currently waiting on, either as a property of the Fiber
   (Fiber::$pollHandle) or as a Fiber::suspendPolling(PollHandle $pollHandle, mixed $value = null) method.

4. Now internal IO methods can be changed to start a pollable Fiber
   instead of blocking the execution if they are started in a specific way
   (e.g. by a then introduced spawn() call).

5. With all that in place, userland can now create their own
   Scheduler/Rector. The Core could also include a simple default
   implementation used the PollContext/PollWatcher in addition with a
   scheduling policy for other Fibers.

Kind regards
Dennis

Hi Edmond,

First of all, sorry for my bad English, and thanks a lot for the huge
amount of work you’ve put into this proposal.
You researched, wrote the RFC, implemented it, and answered tons of
questions. Really impressive.

I have one suggestion and two small questions.

Suggestion

Maybe keep the base |Awaitable| internal and expose two userland
interfaces that match the two cases described in the RFC:

|// Single state change, idempotent read, same result on each await
interface Future extends Awaitable {} // Multiple state changes, each
await may observe a new state interface Streamable extends Awaitable {} |

This makes the single-shot vs multi-shot difference explicit and easier
for tools and libraries to reason about.
Later on, it could even be extended with something like:

|interface Retryable extends Awaitable {}|

Questions (self-cancellation)

What happens here?

|use function Async\spawn; use function Async\suspend; $coroutine =
spawn(function() use (&$coroutine) { $coroutine->cancel(new
\Async\CancellationError("Self-cancelled")); echo "Before suspend\n";
suspend(); echo "After suspend\n"; // should this run? return
"completed"; }); await($coroutine); |

Can a cancelled coroutine suspend?
And if a function that yields is called after the cancel, should that
suspension still happen?

And what about this one?

|use function Async\spawn; $coroutine2 = spawn(function() use
(&$coroutine2) { $coroutine2->cancel(new
\Async\CancellationError("Self-cancelled")); echo "Before exception\n";
throw new \RuntimeException("boom after cancel"); }); await($coroutine2); |

Which error does |await()| throw in this case — |CancellationError| or
|RuntimeException|?
It’d be great to clarify that in the docs, since it affects where people
put cleanup, logging, etc.

Again, thanks for the work, especially on such an important feature for
PHP’s future.
Hope to see it in php-src soon.

Best,
Luís Vinícius