Streams Poll API by bukka · Pull Request #19572 · php/php-src

bukka · 2025-08-24T12:09:31Z

This introduces a new API for polling that supports various backends:

epoll for Linux
kqueue for MacOS and BSD variants
WSAPoll for Windows
Event ports for Solaris and Illumos
poll for the rest

The API tries to reflect primarily epoll and the rest is done in a way so it is compatible.

bukka · 2025-08-24T12:43:54Z

Currently just kqueue and poll on MacOS are properly tested. The epoll should be easy to get tested but will need to then properly look to iocp and event ports. For event ports I will need to first set OmniOS (Illumos) up.

bukka · 2025-08-24T20:11:35Z

So epoll looks good and all tests passing there.

Tha API also builds on Windows but unsuprisingly the iocp backend does not really work well so this is someting that I will be looking to.

And then event ports will likely need some work as well which I will look then too.

This introduces various IO polling backend including epoll, kqueue, event ports, poll and WSAPoll. It makes the usage compatible between backends.

It makes use of internal polling API and exposes its functionality to user space.

nicolas-grekas · 2026-05-25T16:06:32Z

+}
+?>
+--EXPECT--
+ERROR: Handle already added


why do we need to throw when this happens? can't we just ignore?

The issue is that the second call can have different events and data and that would get completely ignored. I should probably change the second call to:

pt_stream_poll_add($poll_ctx, $socket1w, [Io\Poll\Event::Read], "socket_ignored_data_and_event");

to make it clearer...

well that read even doesn't really make much sense for write socket but you get what I mean :)

DanielEScherzer

not going to pretend like I fully understand this, but some comments

DanielEScherzer · 2026-05-25T20:17:03Z

+  ])
+
+  dnl Set poll mechanisms including poll that is always available
+  poll_mechanisms="$poll_mechanisms poll"


not sure if this matters, but $poll_mechanisms will always have a leading space (unless autoconf removes those automatically???) - if you start with poll being included at the top, then there wouldn't be that space

DanielEScherzer · 2026-05-25T20:19:49Z

+   +----------------------------------------------------------------------+
+   | Copyright (c) The PHP Group                                          |
+   +----------------------------------------------------------------------+
+   | This source file is subject to version 3.01 of the PHP license,      |


will need update for the license change

DanielEScherzer · 2026-05-25T20:20:29Z

+
+/* Accessor macros */
+#define PHP_POLL_CONTEXT_OBJ_FROM_ZOBJ(_obj) \
+	((php_io_poll_context_object *) ((char *) (_obj) - XtOffsetOf(php_io_poll_context_object, std)))


will need update for XtOffsetOf removal

DanielEScherzer · 2026-05-25T20:21:38Z

+#define PHP_POLL_CONTEXT_OBJ_FROM_ZV(_zv) PHP_POLL_CONTEXT_OBJ_FROM_ZOBJ(Z_OBJ_P(_zv))
+
+/* Helper to throw failed operation exceptions with error code */
+static inline void php_io_poll_throw_failed_operation(


I'm not sure that this kind of helper function actually helps - it me, it just adds another level of indirection. C.f. #21399 - what is the issue with using zend_throw_exception directly?

DanielEScherzer · 2026-05-25T20:23:18Z

+		case PHP_POLL_BACKEND_WSAPOLL:
+			return "WSAPoll";
+		case PHP_POLL_BACKEND_AUTO:
+		default:


I would suggest that default be marked as unreachable rather than working - if someone casts an invalid integer to php_poll_backend_type we should fail loudly imo

DanielEScherzer · 2026-05-25T20:45:25Z

+PHPAPI bool php_poll_backend_supports_edge_triggering(php_poll_backend_type backend)
+{
+	if (backend == PHP_POLL_BACKEND_AUTO) {
+		/* Check the first (best) available backend */
+		if (num_registered_backends > 0 && registered_backends[0]) {
+			return registered_backends[0]->supports_et;
+		}
+		return false;
+	}
+
+	for (int i = 0; i < num_registered_backends; i++) {
+		if (registered_backends[i] && registered_backends[i]->type == backend) {
+			return registered_backends[i]->supports_et;
+		}
+	}
+
+	return false;
+}


seems like this can be deduplicated with php_poll_get_backend_ops()

Suggested change

PHPAPI bool php_poll_backend_supports_edge_triggering(php_poll_backend_type backend)

{

if (backend == PHP_POLL_BACKEND_AUTO) {

/* Check the first (best) available backend */

if (num_registered_backends > 0 && registered_backends[0]) {

return registered_backends[0]->supports_et;

}

return false;

}

for (int i = 0; i < num_registered_backends; i++) {

if (registered_backends[i] && registered_backends[i]->type == backend) {

return registered_backends[i]->supports_et;

}

}

return false;

}

PHPAPI bool php_poll_backend_supports_edge_triggering(php_poll_backend_type backend)

{

const php_poll_backend_ops *backend_ops = php_poll_get_backend_ops(backend);

return backend_ops && backend_ops->supports_et;

}

DanielEScherzer · 2026-05-25T20:48:16Z

+}
+
+/* Get backend name */
+PHPAPI const char *php_poll_backend_name(php_poll_ctx *ctx)


can you document why this function and the ones below support having a missing context? Or a context with no backend_ops set? That seems confusing

DanielEScherzer · 2026-05-25T23:54:26Z

+php_poll_handle_ops php_poll_handle_default_ops = { .get_fd = php_poll_handle_default_get_fd,
+	.is_valid = php_poll_handle_default_is_valid,
+	.cleanup = php_poll_handle_default_cleanup };


this is a bit hard to read, suggest formatting like the other struct initializations

Suggested change

php_poll_handle_ops php_poll_handle_default_ops = { .get_fd = php_poll_handle_default_get_fd,

.is_valid = php_poll_handle_default_is_valid,

.cleanup = php_poll_handle_default_cleanup };

php_poll_handle_ops php_poll_handle_default_ops = {

.get_fd = php_poll_handle_default_get_fd,

.is_valid = php_poll_handle_default_is_valid,

.cleanup = php_poll_handle_default_cleanup

};

DanielEScherzer · 2026-05-25T23:55:39Z

+#define PHP_POLL_ERROR_CODE_NOSUPPORT   11
+
+/* Error codes */
+typedef enum {


I guess I'm a bit confused as to the difference between the defined codes and the corresponding enum cases - why not always use the enum cases, and just put the underlying literals integers in the enum definition?

DanielEScherzer · 2026-05-25T23:56:18Z

+	 * @param handle The handle object
+	 * @return true if valid, false if invalid
+	 */
+	int (*is_valid)(php_poll_handle_object *handle);


the documentation says that this returns true/false

Suggested change

int (*is_valid)(php_poll_handle_object *handle);

bool (*is_valid)(php_poll_handle_object *handle);

github-actions Bot added Category: Build System SAPI: fpm Extension: standard ABI break labels Aug 24, 2025

bukka added the Category: Streams label Aug 24, 2025

bukka force-pushed the poll_api branch from 73fa0b9 to 337c7ff Compare August 24, 2025 17:40

github-actions Bot added the Extension: reflection label Aug 24, 2025

bukka force-pushed the poll_api branch 3 times, most recently from 2d53464 to 4edefc1 Compare September 24, 2025 20:28

bukka force-pushed the poll_api branch 2 times, most recently from e2f2ec8 to 22689ad Compare October 30, 2025 20:55

bukka marked this pull request as ready for review October 30, 2025 20:55

bukka requested review from DanielEScherzer and kocsismate as code owners October 30, 2025 20:55

bukka added the STF: Streams label Oct 30, 2025

bukka force-pushed the poll_api branch 2 times, most recently from a68b8be to 1d55dce Compare December 24, 2025 00:18

bukka force-pushed the poll_api branch 2 times, most recently from a74b2b8 to d48b64f Compare February 22, 2026 15:43

bukka force-pushed the poll_api branch 2 times, most recently from 9c3c346 to 1378608 Compare March 15, 2026 16:17

bukka added 2 commits April 25, 2026 21:10

Add internal polling API

fc525ab

This introduces various IO polling backend including epoll, kqueue, event ports, poll and WSAPoll. It makes the usage compatible between backends.

Introduce Io\Poll userspace API

675c42e

It makes use of internal polling API and exposes its functionality to user space.

bukka force-pushed the poll_api branch from 1378608 to 675c42e Compare April 25, 2026 21:46

nicolas-grekas reviewed May 25, 2026

View reviewed changes

DanielEScherzer reviewed May 25, 2026

View reviewed changes

	int (is_valid)(php_poll_handle_object handle);
	bool (is_valid)(php_poll_handle_object handle);

Conversation

bukka commented Aug 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bukka commented Aug 24, 2025

Uh oh!

bukka commented Aug 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DanielEScherzer left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bukka commented Aug 24, 2025 •

edited

Loading