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. Revolt v1.0.8 with StreamSelectDriver (default, no ext-ev/ext-uv). ext-eventloop using kqueue driver.

Benchmark	Revolt	ext-eventloop	Speedup
`defer()` dispatch	715,053 ops/sec	3,712,263 ops/sec	5.2x
`delay(0)` dispatch	234,229 ops/sec	2,832,500 ops/sec	12.1x
`repeat()` dispatch	679,452 ops/sec	17,794,516 ops/sec	26.2x
I/O register + cancel	2,109,267 ops/sec	7,635,677 ops/sec	3.6x
Fiber suspend/resume	221,776 ops/sec	248,738 ops/sec	1.1x

Note: Revolt was tested with its default StreamSelectDriver. With ext-ev or ext-uv backends, Revolt's I/O performance would be higher, though callback dispatch overhead remains in PHP userland. Fiber performance is nearly identical because suspend()/resume() is handled by the Zend Engine in both cases.

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 26 .phpt tests covering defer, delay, repeat, I/O watchers, signals, suspensions, error handling, and edge cases.

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