Re: [RFC] Polling API

Hi Am 2025-10-30 22:06, schrieb Jakub Zelenka:

I would like to introduce a new polling API RFC that is part of my stream evolution work: https://wiki.php.net/rfc/poll_api

1. Thank you for the RFC. I've taken a first skim of the proposal and it immediately raised the question of naming and namespacing in particular. Our naming policy at https://github.com/php/policies/blob/main/coding-standards-and-naming.rst#bundled-extensions says that “namespaces SHOULD be used” and given that this is a completely new API, I think we should namespace them. My understanding is that the proposed API relies on a file descriptor and not something like a timeout. It therefore makes sense to me to put it into a namespace Io\Poll; or similar. We would then also have:

    namespace Io;
    class IoException extends \Exception {}
    namespace Io\Poll;
    class PollException extends \Io\IoException {}

The StreamPollHandle method should possibly be placed in the global namespace still, since the stream functions are sitting there - and a SocketPollHandle would of course be sitting in the namespace of the Sockets extension. 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. 3. Exception-wise. StreamPollHandle::__construct(): This should probably be a ValueError, not a PollException, since passing an invalid stream is a programmer error. 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.”). 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”. Is this an error situation that users will encounter in the real world? Similarly, when can PollContext::wait() fail? 4. PollBackend Is the availability of the backends known at compile time of PHP or at runtime only? Depending on that it might make sense to only conditionally define the enum cases, allowing users to check availability with defined() or checking the output of ::cases(). Alternatively, a public static function getAvailableBackends(): array could be added. -------- I'll give the proposal a more in-depth read at a later point, but this email should already provide for some discussion points. Best regards Tim Düsterhus