PHP True Async RFC

It's done. Thank you. Ed.

I wonder if there are ways it can be split into smaller pieces, so that

I can suggest the following workflow: 1. *Approval of the core concept*: Changes affecting the language core. 2. *Decision on the low-level API*: Async\wait + Resume + microtask. Should it be exposed to PHP developers or not? (I don’t have a definitive answer). This is a crucial point that impacts 30-40% of the code. If the decision is made to hide this API, the code will need to be adjusted. Next, the RFC can be split into two parts: - *Low-level*: Basic PHP primitive functions + C API - *High-level*: Future, await, Channel, and maybe Pool. So the process would be: 3. Approval of the *Low-level RFC* 4. Approval of the *High-level RFC*. Step 4 depends on Step 3 in terms of implementation but is almost independent in terms of *semantics*. This means it can be discussed separately and more freely. Additionally, the *Low-level API* can be released independently, allowing PHP extensions to adopt concurrency earlier. As for function names, I really hope for your support in this matter because it's far from trivial. Thanks, Ed.

On Sat, Mar 1, 2025, at 18:20, Rowan Tommins [IMSoP] wrote:

I second this, and as a long time user of amphp, go, and C#, I’d be coming into it with a specific mindset. My only thing so far is that it appears the scheduler cannot be replaced; at least, easily. I don’t know if we would do so over on FrankenPHP, but it would be interesting to replace the scheduler with something that utilized go-routines for true multi-threading. Whether that works or not, is a whole different can of worms. I’m compiling a deeper review, but that speaks more to the implementation than the spec. — Rob

The execution order, which is *part of the contract*, is as follows: 1. Microtasks are executed first. 2. Then I/O events and OS signals are processed. 3. Then timer events are executed. 4. Only after that are fibers scheduled for execution. In the current implementation, fibers are stored in *a queue without priorities* (this is not a random choice). During one cycle period, only one fiber is taken from the queue. This results in the following code (I've removed unnecessary details): do { execute_microtasks_handler(); has_handles = execute_callbacks_handler(circular_buffer_is_not_empty(&ASYNC_G(deferred_resumes))); execute_microtasks_handler(); bool was_executed = execute_next_fiber_handler(); if (UNEXPECTED( false == has_handles && false == was_executed && zend_hash_num_elements(&ASYNC_G(fibers_state)) > 0 && circular_buffer_is_empty(&ASYNC_G(deferred_resumes)) && circular_buffer_is_empty(&ASYNC_G(microtasks)) && resolve_deadlocks() )) { break; } } while (zend_hash_num_elements(&ASYNC_G(fibers_state)) > 0 || circular_buffer_is_not_empty(&ASYNC_G(microtasks)) || reactor_loop_alive_fn() ); If we go into details, it is also noticeable that microtasks are executed twice - before and after event processing - because an event handler might enqueue a microtask, and the loop ensures that this code executes as early as possible. The contract for the execution order of microtasks and events is important because it must be considered when developing event handlers. The concurrent iterator relies on this rule. However, making assumptions about when a fiber will be executed is *not* part of the contract, if only because this algorithm can be changed at any moment. *// Execution is paused until the fiber completes* $result = Async\await(

So is it possible to change the execution order and optimize context switches? Yes, there are ways to do this. However, it would require modifying the Fiber code, possibly in a significant way (I haven't explored this aspect in depth). But… let's consider whether this would be a good idea. We have a web server. A single thread is handling five requests. They all compete with each other because this is a typical application interacting with MySQL. In each Fiber, you send a query and wait for the result as quickly as possible. In what case should we create a new coroutine within a request handler? The answer: usually, we do this when we want to run something in the background while continuing to process the request and return a response as soon as possible. In this paradigm, it is beneficial to execute coroutines in the order they were enqueued. For other scenarios, it might be a better approach for a child coroutine to execute immediately. In that case, these scenarios should be considered, and it may be worth introducing specific semantics for such cases. Won't php code behave exactly the same as it did before once enabling the

Suppose we have a sleep() function. Normally, it calls php_sleep((unsigned int)num). The php_sleep function blocks the execution of the thread. But we need to add an alternative path: if (IN_ASYNC_CONTEXT) { async_wait_timeout((unsigned int) num * 1000, NULL); RETURN_LONG(0); } The IN_ASYNC_CONTEXT condition consists of two points: - The current execution context is inside a *Fiber*. - The *Scheduler* is active. What’s the difference? If the *Scheduler* is not active, calling sleep() will block the entire *Thread* because, without an event loop, it simply cannot correctly handle concurrency. However, if the *Scheduler* is active, the code will set up handlers and return control to the "main loop", which will pick the next Fiber from the queue, and so on. This means that *without a Scheduler and Reactor, concurrent execution is impossible (*without additional effort*)*. From the perspective of a PHP developer, if they are working with *AMPHP/Swoole*, nothing changes, because the code inside the if condition will *never execute* in their case. Does this change the execution order inside a *Fiber*? No. If you had code working with *RabbitMQ sockets*, and you copied this code into a *Fiber*, then enabled concurrency, it would work exactly the same way. If the code used *blocking sockets*, the *Fiber* would yield control to the *Scheduler*. And if two such *Fibers* are running, they will start working with *RabbitMQ sequentially*. Of course, each *Fiber* should use a different socket. The same applies to *CURL*. Do you have an existing module that sends requests to a service using *CURL* in a synchronous style? Just copy the code into a coroutine. This means *almost* 98% transparency. Why *almost*? Because there might be nuances in *helper functions* and *internal states*. There may also be *differences in OS state management* or *file system*, which could affect the final result.

once* during the entire lifecycle of the application. If an error occurs and is not handled, the application should *terminate*. This is not a technical limitation but rather a *logical constraint*. If launchScheduler() were replaced with a CLI option, such as php --enable-scheduler, where the *Scheduler* is implicitly activated, then it would be like the *last line of code *it must exist *only once*. Will this change the way os signals are handled then? Will it break compatibility if a

in Windows, which provides a few seconds before the process is forcibly terminated. There are signals intended for *application termination*, such as *SIGBREAK* or *CTRL-C*, which should typically be handled in *only one place* in the application. Developers are often tempted to insert signal handlers in multiple locations, making the code dependent on the environment. But more importantly, this *should not happen at all*. *True Async* explicitly defines a *Flow* for emergency or unexpected application termination. Attempting to disrupt this *Flow* by adding a custom termination signal handler introduces *ambiguity*. There should be *only one* termination handler. And at the end of its execution, it *must* call gracefulShutdown. As for *pcntl*, this will need to be tested.

If a *Fiber* is never resumed, it means the application has completely crashed with no way to recover :) The RFC has *two sections* dedicated to this issue: *Cancellation Operation* + *Graceful Shutdown*. If the application *terminates due to an unhandled exception*, *all Fibers must be executed*. Any *Fiber* can be canceled *at any time*, and there is *no need* to use *explicit Cancellation*, which I personally find an inconvenient pattern. The RFC doesn’t mention the stack trace. Will it throw away any information

This is literally *"exception transfer"*. The stack trace will be exactly the same as if the exception were thrown at the call site. To be honest, I haven’t had enough time to thoroughly test this. Let's try it: <?php Async\async(function() { echo "async function 1\n"; Async\async(function() { echo "2\n"; throw new Error("Error"); }); }); echo "start\n"; try { Async\launchScheduler(); } catch (\Throwable $exception) { print_r($exception); } echo "end\n"; ?> 004+ Error Object 005+ ( 006+ [message:protected] => Error 007+ [string:Error:private] => 008+ [code:protected] => 0 009+ [file:protected] => async.php 010+ [line:protected] => 8 011+ [trace:Error:private] => Array 012+ ( 013+ [0] => Array 014+ ( 015+ [function] => {closure:{closure:async.php:3}:6} 016+ [args] => Array 017+ ( 018+ ) 019+ ) 020+ [1] => Array 021+ ( 022+ [file] => async.php 023+ [line] => 14 024+ [function] => Async\launchScheduler 025+ [args] => Array 026+ ( 027+ ) 028+ ) 029+ ) 030+ [previous:Error:private] => 031+ ) Seems perfectly correct. What will calling exit or die do? I completely forgot about them! Well, of course, Swoole override them. This needs to be added to the TODO. Why is this the case? For example, consider a *long-running* application where a *service* is a class that remains in memory continuously. The *web server* receives an HTTP request and starts a *Fiber* for each request. Each request has its own *User Session ID*. You want to call a service function, but you *don’t* want to pass the *Session ID* every time, because there are also *5-10 other request-related variables*. However, you *cannot* simply store the *Session ID* in a class property, because *context switching is unpredictable*. At one moment, you're handling *Request #1*, and a second later, you're already processing *Request #2*. When a *Fiber* creates another *Fiber*, it copies a *reference* to the *context object*, which has *minimal performance impact* while maintaining execution *environment consistency*. *Closure variables work as expected *they are pure *closures* with no modifications. I didn’t mean that *True Async* breaks anything at the language level. The issue is *logical*: You *cannot* use a *global variable* in two *Fibers*, modify it, read it, and expect its state to remain *consistent*. By this point we have covered FiberHandle, Resume, and Contexts. Now we

*Futures* and *Notifiers* are two different patterns. - A *Future* changes its state *only once*. - A *Notifier* generates *one or more* events. - Internally, *Future* uses *Notifier*. In the *RFC*, I mention that these are essentially *two APIs*: - *High-level API* - *Low-level API* One of the open questions is whether both APIs should remain in *PHP-land*. The *low-level API* allows for close interaction with the *event loop*, which might be useful if someone wants to write a *service* in PHP that requires this level of control. Additionally, this API helps *minimize Fiber context switches*, since its callbacks execute *without switching*. This is *both an advantage and a disadvantage*.

And I agree that it's better to remove unnecessary methods than to let programmers shoot themselves in the foot. As for the single producer method, I am not sure why you would use this.

Yes, in other languages there are no explicit restrictions. If the single producer approach is indeed rarely used, then it's not such an important feature to include. However, I lack certainty on whether it's truly a rare case. On the other hand, these functions are inexpensive to implement and do not affect performance. Moreover, they have another drawback: they increase the number of behavioral variants in a single class, which seems a more significant disadvantage than the frequency of use. It isn't clear what happens when `trySend` fails. Is this an error or does nothing?

Thinking through it, there may be cases where `trySend` is valid, Code using tryReceive could be useful in cases where a channel is used to implement a pool. Suppose you need to retrieve an object from the pool, but if it's not available, you’d prefer to do something else (like throw an exception) rather than block the fiber. Overall, though, you’re right — it’s an antipattern. It’s better to implement the pool as an explicit class and reserve channels for their classic use. Can you expand on what this means in the RFC? Why expose it if it shouldn't

I answered a similar question above.

behavior. I love an iterative approach: prototype => RFC => prototype => RFC. Thank you for the excellent remarks and analysis! Ed.

Hi there, I would also like to highlight some interesting ideas that I find being useful to consider. Recently Bend programming language has been released, and it incorporates a completely different view on the conception of "code", in the definition of "what it is" and "how it should be interpreted". While we interpret it as a sequence of instructions, the proper way of seeing it is the graph of instructions. On every step we reduce that graph, by running the code of the nodes current node depends on. Therefore, basically everything could paralleled w/o the need to have fancy management of threads and other low-level things. For example, having this code: $foo = foo(); $bar = bar(); $baz = $foo + $bar; If it was run in Bend, it would be interpreted so that foo() and bar() functions are executed in parallel, and $baz = $foo + $bar is executed afterwards, since this computation depends on the other two. The key, most excellently beautiful feature here is that all async management is under the hood, exposing nothing for the developers to be bothered with. That being said, I also want to mention that Bend has a primitive for concurrent loops. Actually, they used another solution, different from loops, since loops are sequential by their essense (iterative one by one). They introduced a concurrent alternative for loops with "bend" keyword, allowing data structures to be traversed in parallel. I think this is actually "the right way" of doing parallel processing in general and async programming in particular, and this is greatly to be considered for having at least some principles applied in PHP. What I think it could be. async function baz(): int { $foo = foo(); $bar = bar(); return $foo + $bar; } // value is returned just like from any other ordinary function $val = baz(); Function above could run foo() in one fiber, and bar() in another, both of them being awaited at the return statement (at the first statement where the value is actually used / referenced, if we put it more generally) so that actual values could be taken. In other words, async function is not promise-based as in other languages that suffer from red blue function problem, but rather it is function with coroutine flow of execution, so that foo() is executed as the first coroutine, and when it blocks, then bar() is executed until it also blocks. Then, at plus operator being evaluated, $foo is awaited, and $bar is awaited, since they are necessary parts for + operation to complete. Best regards

On 4 March 2025 18:36:37 GMT, Larry Garfield <larry@garfieldtech.com> wrote:

So would I, I've actually thought about it a lot... But more importantly, this highlights something important about that Python library: it is built *on top of* a native async/await system which is baked into the language (note the example uses "async with", not normal "with"). That reinforces my earlier feeling that this RFC is trying to do far too much at once - it's not just about "low-level vs high-level", there's multiple whole features here: - asynchronous versions of native functions, and presumably a C API for writing those in extensions - facilities for writing coroutines (async/await, but not as keywords) - deferrable "microtasks" - event/signal handling functionality - communication between threads/fibers via Channels - a facility for launching coroutines concurrently (as Python demonstrates, this can be separate from how the coroutines themselves are written) - maybe more that I've overlooked while trying to digest the RFC Having all of those would be amazing, but every one of them deserves its own discussion, and several can be left to userland or as future scope in an initial implementation. Rowan Tommins [IMSoP]

Good day, Larry.

proposal. Thanks!

state not present in that function.

methods on them that do, um, stuff.

functions. Suppose these shortcomings don’t exist, and we have implemented the boldest scenario imaginable. We introduce Structured Concurrency, remove low-level elements, and possibly even get rid of Future. Of course, there are no functions like startScheduler or anything like that. 1. In this case, how should PHP handle Fiber and all the behavior associated with it? Should Fiber be declared deprecated and removed from the language? What should the flow be? 2. What should be done with I/O functions? Should they remain blocking, with a separate API provided as an extension? 3. Would it be possible to convince the maintainers of XDEBUG and other extensions to rewrite their code to support the new model? ( *If you're reading this question now, please share your opinion.* ) 4. If transparent concurrency is introduced for I/O in point 2, what should be done with Revolt + AMPHP? This would break their code. Should an additional function or option be introduced to switch PHP into "legacy mode"? I share your feelings on many points, but I would like to see some real-world alternative.

Structured concurrency is a great thing. However, I’d like to avoid changing the language syntax and make something closer to Go’s semantics. I’ll think about it and add this idea to my TODO.

such.

async controls.

async. This is good. This is a very elegant solution. Theoretically. However, in practice, if you require explicitly passing the context to all functions, it leads to the following consequences: 1. The semantics of all functions increase by one additional parameter (*Signature bloat*). 2. If an asynchronous call needs to be added to a function, and other functions depend on it, then the semantics of all dependent functions must be changed as well. In strict languages, a hybrid model is often used, or like in Go, where the context is passed explicitly as a synchronization object, but only when necessary. In this example, there is another aspect: the fact that async execution is explicitly limited to a specific scope. This is essentially the same as startScheduler, and it is one of the options I was considering. Of course, startScheduler can be replaced with a construction like async(function() { ... }). This means that async execution is only active within the closure, and coroutines can only be created inside that closure. This is one of the semantic solutions that allows removing startScheduler, but at the implementation level, it is exactly the same. What do you think about this?

Context object is wise; Why not?

Static variables inside a function are also global state. Are you against static variables?

stuff quite naturally. Possibly with: How will a context with open string keys help preserve service data that the service doesn't want to expose to anyone? The Key() solution is essentially the same as Symbol in JS, which is used for the same purpose. Of course, we could add a coroutine static $var construct to the language syntax. But it's all the same just syntactic sugar that would require more code to support.

This semantics require the programmer to remember that two variables actually point to the same object. If a function has multiple channels, this makes the code quite verbose. Additionally, such channels are inconvenient to store in lists because their structure becomes more complex. I would suggest a slightly different solution: <code php> $in = new Channel()->getProducer(); async myFunction($in->getConsumer()); <code> This semantics do not restrict the programmer in usage patterns while still allowing interaction with the channel through a well-defined contract. Thanks for the great examples, and a special thanks for the article. I also like the definition of context. Ed

Hello, Jakub.

clarify the primary design that we want to go for.

(threads) in it.

supported), then we should take it into the account from the beginning and add restrictions to prevent race conditions.

If you mean multitasking, i.e., executing coroutines in different OS threads, then this feature is far beyond the scope of this RFC and would require significant changes to the PHP core (Memory manager first). And even if we imagine that such changes are made, eliminating data races without breaking the language is, to put it mildly, a questionable task from the current perspective. Although this RFC raises the question of whether a concurrent version without multitasking is worth implementing at all, my opinion is positive. For PHP, this could be sufficient as a language primarily used in the context of asynchronous I/O, whereas a multitasking version may never happen. I will likely pose this as a direct question in the final part of this RFC. Thanks! Ed.

On Sat, Mar 8, 2025, at 1:05 AM, Edmond Dantes wrote:

Yes.

This is incorrect. "Create an async bounded context playpen" (what I called "async" in my example) and "start a fiber/thread/task" (what I called "spawn") are two *separate* operations, and must remain so. create space for async stuff { start async task a(); start async task b(); } However those get spelled, they're necessarily separate things. If any creation of a new async task also creates a new async context, then we no longer have the ability to run multiple tasks in parallel in the same context. Which is, as I understand it, kinda the point. I also don't believe that an async bounded context necessarily needs to be a function, as doing so introduces a lot of extra complexity for the user when they need to manually "use" things. (Though perhaps sometimes we can have a shorthand for that; that comes later.) I am also still very much against allowing tasks to "detach". If a thread is allowed to escape its bounded context, then I can no longer rely on that context being bounded. It removes the very guarantee that we're trying to provide. There are better ways to handle "throwing off a long-running background task." (See below.) Edmond, correct me if I'm wrong here, but in practice, the *only* places that it makes sense to switch fibers are: 1. At an otherwise-blocking IO call. 2. In a very long running CPU task, where the task is easily broken up into logical pieces so that we can interleave it with shorter tasks in the same process. This is only really necessary when running a shared single process for multiple requests. And in this proposal, IO operations auto-switch between blocking and thread-sharing as appropriate. To be more concrete, let's consider specific use cases that should be addressed: 1. Multiplexing IO, within an otherwise sync context like PHP-FPM I predict that, in the near term, this will be the most common usage pattern. (Long term, who knows.) This one is easily solvable; it's basically par_map() and variations therein. // Creates a context in which async is allowed to happen. IO operations auto async $ctx = new AsyncContext() { $val1 = spawn task1(); $val2 = spawn task2(); // Do stuff with those values. } // We are absolutely certain nothing started in that block is still running. (I'm still unclear if $val1 and $val2 should be values or a Future object. Possibly the latter.) 4. Shared-process async server This is the ReactPHP/Swoole space. This... honestly gets kind of easy. Wrap the entire application in an async {} block. Boom. All IO is now async. <?php async { while (true) { $request = spawn listen_for_request(); spawn handle_request($request); } } Importantly, since IO is the primary switch point, and IO automatically deals with thread switching, my DB-query-heavy Repository object doesn't care if I'm doing this or not. If each $handler (controller, whatever) is written 100% sync, with lots of IO... it still works fine. 3. Set-and-forget background job This is the logger example, but probably also queue tasks, etc. This is where the request for detaching comes from. I would argue detaching is both the wrong approach, and an unnecessary one. Because you can send data to fibers from OTHER contexts... via channels. So rather than this: spawn detatch log('message'); // Who the hell knows when this will complete, or if it ever does. We have this: async { $logger = new AsyncLogger(); $channel = $logger->inputChannel(); spawn handler($logChannel); } function handler($logger) { async { while (true) { $request = spawn listen_for_request(); spawn handle_request($request, $logChannel); } // An exception could get us to here. } } function handle_request($request, $logChannel) { $logChannel->send($request->url()); // Do other complex stuff with the request. } This is probably not the ideal way to structure it in practice, but it should get the point across. The background logger fiber already exists in the parent async playpen. That's OK! We can send messages to it via a channel. It can keep running after the inner async block ends. The logger fiber doesn't need to be attached, because it was already attached to a parent playpen anyway! This means passing either a channel-enabled logger instance around (probably better for BC; this should be easy to do behind PSR-3) or the sending channel itself. I'm sure someone will object that is too much work. However, it is no more, or less, work than passing a PSR-3 logger to services today. And in practice "your DI container handles that, stop worrying" is a common and effective answer. An async-aware DI Container could have an Async-aware PSR-3 logger it passes to various services like any other boring PSR-3 instance. That logger forwards the message across a channel to a waiting parent-playpen-bound fiber, where it just enters the rotation of other fibers getting run. Services don't need to be modified at all. We don't need to have dangling fibers. And for smaller, more contained cases, eh, Go has shown that "just pass the channel around and move on with life" can be an effective approach. The only caveat is you can't pass a channel-based logger to a scope that will be called outside of an async playpen... But that would be the case anyway, so it's not really an issue. There's still the context question, as well as whether spawn is a method on a context object or a keyword, but I think this gets us to 80% of what the original RFC tries to provide, with 20% of the mental overhead. --Larry Garfield