[RFC] Polling API

Hi, On Fri, Oct 31, 2025 at 10:40 AM Tim Düsterhus <tim@bastelstu.be> wrote:

I thought about this and think this might be a good idea. Just to note internally it might not always be a fd. For example, TimerHandle might implement internal API not requiring fd because some platforms (e.g. kqueue ones) don't use it but from the API design (and on Linux), it is fd based so putting that to Io namespace might make sense. The thing is that I also started working on new IO copy API: https://github.com/php/php-src/compare/master...bukka:php-src:io_copy . This is just a stub but it aims to introduce new IO layer (initial mainly for copying but potentially cover more operations) and it should also contain a new IO ring (on Linux based on io_uring) variant that could be potentially also exposed in some form. I will get it to some working form in the coming weeks and then thing how to organise it with the poll.

Yeah those could stay in global and just extend Io\Poll\Handle.

I missed that they should not be backed. I just saw `enum AdjacentPosition : string` in Dom so thought that it's fine to use it... Will change it.

This makes sense.

This makes sense and I will introduce more exceptions. I will not use exception per errno but some middle ground is a good idea. Maybe per op exception with codes representing specific errors would be make sense?

It fails if the same fd is added. This is also limitation of backends (e.g. epoll does not allow the same fd to be added twice). I got error code for the specific errors so this should be probably exposed as well. It would still make sense to differentiate that it's an exception for addition.

Wait might also fail but less likely.

It's compile time but not sure if I like exposing enum only if compiled in as it makes the checks harder. This part is not really something that users should use but it's really more for testing purpose. In reality everyone should just use default Auto... But getAvailableBackends() might make sense even for testing. Maybe it could also have per enum method isAvailable() so user can check that but not sure if it's needed. Kind regards, Jakub

Hi, On Fri, Oct 31, 2025 at 11:58 PM Dennis Birkholz <php@dennis.birkholz.biz> wrote:

I actually planned to use interface initially but there are few issue with it. - as I mentioned above, not all handles will always allow using file descriptors (e.g. timer for kqueue) - abstract class allow internal api defintion and not calling the PHP functions internally (that's how the above can be handled as well) - it would require exposing the actual fd numbers for streams which after some thinking might not be best idea because it would make easier for people to have two streams for a single fd which might cause issues with filtering, buffering and so on.

I put there just those that I actually plan to implement and are relatively straight forward. For mysqli it might require some abstraction to get the mysqlnd stream so would need to check it out first. In other words I haven't fully investigated it yet. But it should be probably added too. Kind regards, Jakub

I don't know what changes this proposal could bring to PHP if the aim is simply to introduce event loop mechanisms like epoll or kqueue.&nbsp;&nbsp; Why not make ext-uv (libuv) or ext-event (libev) built-in PHP extensions, just like ext-curl, ext-xml, or ext-bcmath?&nbsp;&nbsp; These event loop libraries have been thoroughly tested across numerous projects, proving to be extremely stable and reliable. They could serve as the foundational infrastructure for implementing asynchronous IO in PHP. ----- Tianfeng.Han &nbsp; &nbsp; ------------------&nbsp;Original&nbsp;------------------ From: "Larry&nbsp;Garfield"; Date: 2025年11月2日(星期天) 凌晨3:24 To: "php internals"; Subject: Re: [PHP-DEV] [RFC] Polling API &nbsp; On Thu, Oct 30, 2025, at 4:06 PM, Jakub Zelenka wrote: &gt; Hello, &gt; &gt; I would like to introduce a new polling API RFC that is part of my &gt; stream evolution work: &gt; &gt; https://wiki.php.net/rfc/poll_api &gt; &gt; Kind regards, &gt; &gt; Jakub I freely admit to not being fully versed in this area, so take my feedback with however much sodium chloride you feel is appropriate. - Given that a lot of people reading this are probably no more versed in kernel IO polling than I am, a section early on explaining the context of what is even being discussed would be most appreciated. - I really would rather not add more global constants.&nbsp; Better to at minimum make them class constants of a class that the new API provides.&nbsp; (Maybe PollHandle?) - Conversely, I'm unclear why the PollBackend is an enum.&nbsp; That implies the list of backend implementations is fixed and immutable, and not extensible now or in the future.&nbsp; I find that claim suspect, as there are six already.&nbsp; (I find that following the 0-1-many rule in most cases pays off in the long run.) - PollWatcher is created only by PollContext.&nbsp; OK, then please list PollContext first so that reading PollWatcher I have the, er, context for where it fits. - Speaking of, when there's very long code blocks like this I much prefer to break it up to a block per class, so as to minimize codeblock scrolling.&nbsp; That makes it much easier to read and jump around as I figure out how it all works. - How would requesting a specific poll backend be helpful, if it varies by OS?&nbsp; If I'm running on Windows, asking for the Linux backend wouldn't help me much, or vice versa.&nbsp; I don't see the use case here.&nbsp; (Ie, please describe the use case in more detail.) - Who is the target audience for this?&nbsp; I'm pretty sure it's not anything I normally work on, so it's hard for me to judge if certain decisions are good, bad, or "sucky but we have to."&nbsp; Eg, getData() returning "who the hell knows" strikes me as a footgun in waiting, but I don't have enough context to know if that's an inherited problem from elsewhere. Overall, I think my biggest feedback is "please explain better why any of this matters, because I assume it does somehow but don't understand how from the RFC." --Larry Garfield

Hi, On Sat, Nov 1, 2025 at 8:23 PM Larry Garfield <larry@garfieldtech.com> wrote:

I added a section with some basic explanation so users that are more interested in details can easily search for it.

I replaced them with \Io\Poll\Event enum so this should be covered. There are no global constants. The only constants are now on class and they are for error codes.

This is unlikely to grow and if it ever grew, it would happen only as a new feature in new minor version. Or do we have any policy that disallows extending enums? This is just a theoretical concern though because all the main backends are covered. The only one that could be potentially added is a different variant for Windows if WSAPoll shows poor performance as it was the case in past but not sure if anyone will do such work.

Updated.

Fixed.

There is poll supported on all unix variants and then Illumos has also variant of epoll so there are more than one backend for each platform (except Windows that currently support just one). As noted in the RFC, setting of the backend is mostly useful for testing. The actual enum is more useful to get info of the selected backend. Currently the most useful thing is to find out whether edge triggering is possible.

Added a section explaining the motivation and possible users of this API. In terms of getData, we would need to have generics to make it typed as this is for user data. You can see the examples that should give you hopefully some idea how this can be used. Kind regards, Jakub

Hi, On Tue, Dec 9, 2025 at 12:48 PM Derick Rethans <derick@php.net> wrote:

I introduce \Io\Poll\Event enum. It doesn't allow ORing but all functions now accept array of those events which is hopefully good enough and cover this. If we ever introduced something like enum sets supporting OR operator, the functions could accept it in addition to the array.

It's no longer a backed enum so this is sorted.

The PollWatcher was introduced on request from Bob so the new objects are not created after each polling. This should be more efficient but to be able to remove it, it needs to be done explicitly because the reference is held so we need to somehow inform context that it can be removed. I think we could introduce API to re-use it in the future but for now leaving clean up to GC is the way. Btw. there isActive() method that still works after removal and it returns false. The modification method will throw exception if used. If you have some suggestion for better API, I will be happy to consider it.

Returning just a single event is not ideal for performance if there are many events so not sure it should be the preferred usage of the API.

I would see it more like introducing waitSingle but it's basically just public function waitSingle(int $timeout = -1): ?PollWatcher { return $this->wait($timeout, 1)[0] ?? null; } so not sure if it's that useful. But if you think, it's worth it, I can add it..?

The timer and signal are actually file descriptors on Linux (timerfd and signalfd) but you are right that this is not always the case. This is however internal and that abstract class offers a different API for internal extending that is more flexible. It means it won't call getFileDescriptor() for internal classes but use direct C API. That getFileDescriptor() is really meant for user classes that extend PollHandle so they do something rather than extending class with empty interface.

So in this case I think I would need to come up with some different way how to allow polling without file descriptor for user classes otherwise user space class could extend PollHandle and it would just do nothing which I don't think is the right thing. I thought about it and I just don't have any idea what that could be. I think that non fd variants don't make much sense for user space or at least I don't see any reasonable use case. The only other concern I have is that some polling backends allow for

I tried to make it as portable as possible but edge triggering is just not possible to simulate and I think it's worth exposing it even though it doesn't work on Windows and Solaris. I added at least flag in the backend so it's quite simple to check. Kind regards, Jakub

Hi, Thanks for the feedback! On Sun, Jan 18, 2026 at 1:24 PM Tim Düsterhus <tim@bastelstu.be> wrote:

Yeah this makes sense. I used the same convention that is used in streams which means two params so it is changed to: public function wait(int $timeoutSeconds = -1, int $timeoutMicroseconds = 0, int $maxEvents = -1): array {}

I actually thought that it might be nicer to have default method for internal classes but that wouldn't work well for user classes anyway so it's better to make it abstract which I just did.

I have been considering this already and there are reasons why I prefer abstract method here. The abstract method is better for internal implementation and limit overhead of PHP calls that would be required for interface. The advantage is that I can use internal struct API through C operations which allows bypasing the call and can do optimization for some backends - e.g. timeouts for kqueue don't need file descriptor. I also think that there is not really much use case for user space to implement their own handles so such interface would be used only internally anyway. In addition interface would effectively expose the internal stream fd which is currently hidden and makes harder messing up with stream fd which might cause various issues.

Depending on backend it will result either in FailedHandleAddException (epoll, kqueue, possible event ports as well) or on Windows it would likely fail during wait with FailedPollWaitException. So it can be handled by catching FailedPollOperationException. This is however very unlikely edge case so I don't think there is much point to worry about consistency. As I said the use case for implementing custom Handle is a bit moot.

Makes sense. I added it also for Watcher::getTriggeredEvents, Watcher::getWatchedEvents that return list<Event> and Context::wait that returns list<Watcher>.

I don't think it should be error as it is not necessary for user to track removal of watcher (which can also happen automatically for one shot events). It should be just fine to normally recover from this rather than requiring checking for isActive. It's more state issue which is usually handled using exceptions IMHO.

This has been changed as suggested (together with introducing microseconds support for user space). In addition to the above changes I also changed ValueError for passing backend that is not available on the current platform to new BackendUnavailableException as this is more runtime specific issue that application might want to handle rather than forcing users to always use Backend::isAvailable. Basically I feel if something can vary and it's not possible to be immediately caught by developer (because they can develop it on different platform), then it should be more an exception than error. Kind regards, Jakub

вс, 29 мар. 2026 г., 23:54 Jakub Zelenka <bukka@php.net>:

Hi, Jakub! Why do you use get and is methods if we have powerful prioritize with get hooks nowadays? I think that PHP should promote its modern features in its own API.