README

A native PHP extension that brings a high-performance event loop directly into the engine. Inspired by and API-compatible with Revolt -- not a replacement, but a native alternative written in C for zero-overhead async I/O.

Why? Revolt is an excellent userland library. This extension takes the same proven API design and moves it into a PHP extension, eliminating userland dispatch overhead and leveraging OS-level I/O primitives (epoll, kqueue, poll) directly from C.

Key Differences from Revolt

	Revolt	ext-eventloop
Implementation	PHP userland	C extension
Installation	`composer require revolt/event-loop`	`phpize && make install`
I/O backend	Configurable (ev, event, uv)	Auto-detected (epoll / kqueue / poll / select)
Fiber suspension	Yes	Yes
API contract	`Revolt\EventLoop::*`	`EventLoop\EventLoop::*`

The API surface mirrors Revolt's, so migrating between the two is straightforward -- adjust the namespace and you're done.

Requirements

PHP >= 8.1 (Fiber support required)
A POSIX-compatible OS (Linux, macOS, FreeBSD, etc.)

Installation

Via PIE (recommended)

pie install axcherednikov/eventloop

From source

git clone https://github.com/axcherednikov/php-eventloop.git
cd php-eventloop

phpize
./configure --enable-eventloop
make
make test
sudo make install

Then enable the extension:

; php.ini or conf.d/eventloop.ini
extension=eventloop

Verify:

php -m | grep eventloop

Quick Start

<?php

use EventLoop\EventLoop;

// Defer a callback to the next loop tick
EventLoop::defer(function (string $callbackId) {
    echo "Deferred callback executed\n";
});

// Delay execution by 1.5 seconds
EventLoop::delay(1.5, function (string $callbackId) {
    echo "This runs after 1.5 seconds\n";
});

// Repeat every 500ms
$id = EventLoop::repeat(0.5, function (string $callbackId) {
    echo "Tick\n";
});

// Cancel the repeater after 3 seconds
EventLoop::delay(3, function () use ($id) {
    EventLoop::cancel($id);
});

EventLoop::run();

API Reference

All methods are static on EventLoop\EventLoop.

Scheduling

Method	Description
`queue(Closure $closure, mixed ...$args): void`	Queue a microtask for immediate execution
`defer(Closure $closure): string`	Defer to the next event loop iteration
`delay(float $delay, Closure $closure): string`	Execute after `$delay` seconds
`repeat(float $interval, Closure $closure): string`	Execute every `$interval` seconds

I/O Watchers

Method	Description
`onReadable(resource $stream, Closure $closure): string`	Execute when a stream becomes readable
`onWritable(resource $stream, Closure $closure): string`	Execute when a stream becomes writable

Signal Handling

Method	Description
`onSignal(int $signal, Closure $closure): string`	Execute when a signal is received

Callback Management

Method	Description
`enable(string $id): string`	Enable a disabled callback
`disable(string $id): string`	Disable a callback (can be re-enabled)
`cancel(string $id): void`	Permanently cancel a callback
`reference(string $id): string`	Reference a callback (keeps the loop alive)
`unreference(string $id): string`	Unreference a callback
`isEnabled(string $id): bool`	Check if a callback is enabled
`isReferenced(string $id): bool`	Check if a callback is referenced
`getType(string $id): CallbackType`	Get the callback type
`getIdentifiers(): array`	Get all registered callback IDs

Loop Control

Method	Description
`run(): void`	Run the event loop
`stop(): void`	Stop the event loop
`isRunning(): bool`	Check if the loop is running
`getDriver(): string`	Get the active I/O driver name

Error Handling

Method	Description
`setErrorHandler(?Closure $handler): void`	Set the error handler for exceptions in callbacks
`getErrorHandler(): ?Closure`	Get the current error handler

Fiber Suspension

$fiber = new Fiber(function () {
    $suspension = EventLoop::getSuspension();

    EventLoop::defer(function () use ($suspension) {
        $suspension->resume('hello');
    });

    $value = $suspension->suspend(); // "hello"
    echo $value; // "hello"
});

$fiber->start();
EventLoop::run();

Method	Description
`Suspension::suspend(): mixed`	Suspend the current fiber
`Suspension::resume(mixed $value = null): void`	Resume with a value
`Suspension::throw(Throwable $e): void`	Resume by throwing an exception

I/O Drivers

The extension automatically selects the best I/O driver available on your system at compile time. There is no manual configuration needed -- you always get optimal performance for your platform.

Driver	Platforms	Scalability	Notes
epoll	Linux 2.6+	O(1)	Kernel tracks descriptors; returns only ready ones
kqueue	macOS, FreeBSD, OpenBSD	O(1)	Same principle as epoll, native to BSD systems
poll	Any POSIX	O(n)	No descriptor limit, but scans all on every call
select	Universal (fallback)	O(n)	Oldest API, limited to ~1024 descriptors

Selection priority: epoll > kqueue > poll > select. The first one that compiles and initializes successfully wins.

In practice this means:

Linux servers (the most common deployment) get epoll -- handles thousands of connections with near-zero overhead
macOS (local development) gets kqueue -- equally efficient
Older or exotic systems gracefully fall back to poll or select

Check which driver is active:

echo EventLoop::getDriver(); // "epoll" on Linux, "kqueue" on macOS

Benchmarks

Environment: PHP 8.5.4, Apple M1 Max, macOS, 100,000 iterations (average of 3 runs). Revolt v1.0.8 tested with all four available drivers (StreamSelect, Ev, Event, UV). ext-eventloop using kqueue driver.

Benchmark	Revolt StreamSelect	Revolt Ev	Revolt Event	Revolt UV	ext-eventloop
`defer()`	765,598 ops/sec	743,057 ops/sec	733,417 ops/sec	742,926 ops/sec	3,658,412 ops/sec
`delay(0)`	242,383 ops/sec	486,501 ops/sec	464,196 ops/sec	183,585 ops/sec	3,047,625 ops/sec
`repeat(0)`	687,196 ops/sec	707,010 ops/sec	74,708 ops/sec	73,491 ops/sec	17,371,529 ops/sec
I/O register + cancel	2,114,361 ops/sec	2,003,474 ops/sec	1,980,326 ops/sec	1,953,935 ops/sec	7,193,404 ops/sec
Fiber suspend/resume	221,383 ops/sec	220,659 ops/sec	218,318 ops/sec	220,244 ops/sec	243,242 ops/sec

These benchmarks measure callback dispatch and scheduling throughput. The I/O backend (StreamSelect, Ev, Event, UV) primarily affects polling efficiency at high concurrency, not dispatch speed — that's why all four Revolt drivers show similar numbers here. ext-eventloop moves the entire dispatch path into C, which is where the difference comes from. Fiber performance is nearly identical because suspend()/resume() is handled by the Zend Engine directly.

Run the benchmarks yourself →

Migrating from Revolt

The API contract is intentionally compatible. In most cases, a namespace swap is all you need:

- use Revolt\EventLoop;
+ use EventLoop\EventLoop;

If you use Revolt\EventLoop\Suspension:

- use Revolt\EventLoop\Suspension;
+ use EventLoop\Suspension;

Testing

make test

The extension ships with 37 .phpt tests covering defer, delay, repeat, I/O watchers, signals, suspensions, error handling, and edge cases.

Changelog

Release notes are available in CHANGELOG.md.

Acknowledgements

This project is built on the ideas and API design of Revolt by Aaron Piotrowski, Niklas Keller, and contributors. Revolt's clean, well-thought-out API made it the natural foundation for a native implementation. Full credit to the Revolt team for defining the contract that this extension follows.

License

Licensed under the MIT License.

axcherednikov / eventloop

Maintainers

Package info

Statistics

Security