Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:129572
Date: Tue, 9 Dec 2025 11:48:09 +0000 (GMT)
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>
Message-ID: <f591fabd-277a-cfc6-abec-eab650a5b971@php.net>
References: <CAEKnhAFZXqWH20Cy2g6-0c2V1Vd4w-N0M4xefzt6tTEp90+LqQ@mail.gmail.com>
Precedence: list
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
From: derick@php.net (Derick Rethans)

On Thu, 30 Oct 2025, Jakub Zelenka wrote:

> 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

Under "Event Constants", I realised that we can't use enums for this 
due to them needing to be OR'ed, but it would be nice if at some point 
in the future we had a way of doing: PollEvent::Read | PollEvent::Write;

The enum PollBackend (not sure if that needs to be a backed enum), but 
this can not stand:

	case EventPorts = "eventport";

All the others have the case name and value the same, but this one 
misses the 's'.

    /**
     * Remove this watcher from the poll context
     * 
     * After removal, the watcher becomes inactive and cannot be reused.
     */
    public function remove(): void {}

Wouldn't this leave the PollWatcher object as a zombie: ie, it exists, 
but you can't do anything with it. Would it be possible to move this API 
somewhere else, so that the memory manager can just destruct it and 
release the object?

     * @param int $maxEvents Maximum number of events to return (-1 for unlimited)
     * @return array Array of PollWatcher instances that have triggered events
     * @throws PollException If the wait operation fails
     */
    public function wait(int $timeout = -1, int $maxEvents = -1): array {}

I am not sure if I like this returning an array. Would it perhaps be 
better to always return 1 (or 0 in case of non-blocking) events, which 
allows typing the return value as ?PollWatcher?

Alternative, perhaps this can be split up into two methods, wait() and 
waitMultiple() to be able to handle both approaches?

Under "Future Scope", you have (for example) TimerHandle, but as that 
will (have to) extend PollHandle, it makes little sense to have a 
getFileDescriptor() method on PollHandle. Perhaps there should be 
another (abstract) class, so that you can have:

- PollHandle
  - FileDescriptorPollHandle
    - StreamPollHandle
    - SocketPollHandle
    - CurlPollHandle
  - TimerPollHandle
  - SignalPollHandle

The only other concern I have is that some polling backends allow for 
different events to be watched, which makes it harder to write portable 
code.

cheers,
Derick

-- 
https://derickrethans.nl | https://xdebug.org | https://dram.io

Author of Xdebug. Like it? Consider supporting me: https://xdebug.org/support

mastodon: @derickr@phpc.social @xdebug@phpc.social