Re: [RFC] Polling API

From: Date: Sun, 23 Nov 2025 15:05:12 +0000
Subject: Re: [RFC] Polling API
References: 1 2 3  Groups: php.internals 
Request: Send a blank email to internals+get-129407@lists.php.net to get a copy of this message 
Hi

Apologies for the late reply. It was a few busy weeks leading up to the PHP 8.5 Release.

When searching for the RFC text I just noticed that it does not appear to be listed in https://wiki.php.net/rfc#under_discussion yet.

On 10/31/25 13:06, Jakub Zelenka wrote:

2. As for the PollBackend enum.

Is there a reason why this is a backed enum? Generally speaking enums
should not be backed, unless there is a good reason for this. I don't
think there is in this case - and none of the native enums are backed so
far.



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.


I missed that one indeed. That one is a little special, because ext/dom implements an existing API standard, where the API is defined based on string parameters. So there already was a “well-defined” string for each enum case that is needed for better interoperability with the external standard.



In the other cases it probably makes sense to further split the
PollException into purpose-built exceptions according to the Throwable
policy at

https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#throwables
(“The exception message MUST NOT be the only means of distinguishing
exception causes that the user might want to handle differently.”).



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?


Yes, that makes sense to me. I don't exactly know which types of error can appear, but as a developer I am generally not interested in super-granular handling of the errors but rather broad categories. If the details are only available as the code, then that's totally fine and within policy.




As an example PollContext::__construct() should probably throw a
BackendUnavailableException or something like this. For
PollContext::add() I'm wondering in which cases a handle “cannot be
added”.



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.


I see. I was wondering if it would make sense to simply ignore the error, thus making the operation idempotent (more convenient for a high-level language like PHP). But I suppose that doesn't work, because the $data could be different?

Exception-wise this should probably be a DuplicateHandleError (i.e. within the Error hierarchy, since it's a programming error to add duplicate handles).


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.


I'll think about this more when you made a decision and updated the RFC text :-)

Best regards
Tim Düsterhus

Thread (9 messages)

« previous php.internals (#129407) next »