Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:129019
Precedence: list
MIME-Version: 1.0
Date: Fri, 31 Oct 2025 10:40:24 +0100
To: Jakub Zelenka <bukka@php.net>
Cc: PHP internals list <internals@lists.php.net>
Subject: Re: [PHP-DEV] [RFC] Polling API
In-Reply-To: <CAEKnhAFZXqWH20Cy2g6-0c2V1Vd4w-N0M4xefzt6tTEp90+LqQ@mail.gmail.com>
References: <CAEKnhAFZXqWH20Cy2g6-0c2V1Vd4w-N0M4xefzt6tTEp90+LqQ@mail.gmail.com>
Message-ID: <fb357558bd972ce0bdab7dfc8a2787f2@bastelstu.be>
Content-Type: text/plain; charset=UTF-8;
 format=flowed
Content-Transfer-Encoding: 8bit
From: tim@bastelstu.be (=?UTF-8?Q?Tim_D=C3=BCsterhus?=)

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