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
