Revolt

https://revolt.run
Admin
Revolt is an event loop and scheduler for concurrent PHP applications, providing non-blocking I/O...
Tokens:3,835
Snippets:47
Trust Score:6.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Revolt via Composer

Source: https://revolt.run/

Use this command to add the revolt/event-loop package as a dependency in your PHP project.

```bash
composer require revolt/event-loop
```

--------------------------------

### Observe expected output for event loop suspension

Source: https://revolt.run/fundamentals

Shows the console output generated by the suspension example.

```text
++ Suspending to event loop...
++ Executing callback created by EventLoop::repeat()
++ Executing callback created by EventLoop::repeat()
++ Executing callback created by EventLoop::repeat()
++ Executing callback created by EventLoop::repeat()
++ Executing callback created by EventLoop::delay()
++ Suspension::resume() is async!
++ Script end
```

--------------------------------

### Registering a Readability Callback

Source: https://revolt.run/streams

Demonstrates how to monitor a socket for incoming data and handle EOF conditions using EventLoop::onReadable.

```php
<?php

use Revolt\EventLoop;

const IO_GRANULARITY = 32768;

function isStreamDead($socket): bool {
    return !is_resource($socket) || @feof($socket);
}

EventLoop::onReadable($socket, function ($callbackId, $socket) {
    $socketId = (int) $socket;
    $newData = @fread($socket, IO_GRANULARITY);
    if ($newData != "") {
        // There was actually data and not an EOF notification. Let's consume it!
        parseIncrementalData($socketId, $newData);
    } elseif (isStreamDead($socket)) {
        EventLoop::cancel($callbackId);
    }
});

EventLoop::run();
```

--------------------------------

### Suspend execution with Revolt fibers

Source: https://revolt.run/fibers

Demonstrates suspending the main execution context while waiting for STDIN input or a timeout using the Suspension API.

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Revolt\EventLoop;

if (\stream_set_blocking(STDIN, false) !== true) {
    \fwrite(STDERR, "Unable to set STDIN to non-blocking" . PHP_EOL);
    exit(1);
}

print "Write something and hit enter" . PHP_EOL;

$suspension = EventLoop::getSuspension();

$readableId = EventLoop::onReadable(STDIN, function ($id, $stream) use ($suspension): void {
    EventLoop::cancel($id);

    $chunk = \fread($stream, 8192);

    print "Read " . \strlen($chunk) . " bytes" . PHP_EOL;

    $suspension->resume(null);
});

$timeoutId = EventLoop::delay(5, function () use ($readableId, $suspension) {
    EventLoop::cancel($readableId);
    
    print "Timeout reached" . PHP_EOL;

    $suspension->resume(null);
});

$suspension->suspend();

EventLoop::cancel($readableId);
EventLoop::cancel($timeoutId);
```

--------------------------------

### Managing Writability Callbacks

Source: https://revolt.run/streams

Shows the pattern of initializing a writability callback in a disabled state and toggling it only when data is pending to prevent high CPU usage.

```php
<?php

use Revolt\EventLoop;

$callbackId = EventLoop::onWritable(STDOUT, function (): void {});
EventLoop::disable($callbackId);
// ...
EventLoop::enable($callbackId);
// ...
EventLoop::disable($callbackId);
```

--------------------------------

### Enable an event callback

Source: https://revolt.run/fundamentals

Demonstrates using EventLoop::enable() to resume a previously disabled callback.

```php
<?php

use Revolt\EventLoop;

// Register a repeating timer callback
$callbackId = EventLoop::repeat(1, function(): void {
    echo "tick\n";
});

// Disable the callback
EventLoop::disable($callbackId);

EventLoop::defer(function () use ($callbackId): void {
    // Immediately enable the callback when the event loop starts
    EventLoop::enable($callbackId);
    // Now that it's enabled we'll see tick output in our console every second.
});

EventLoop::run();
```

--------------------------------

### Registering a signal callback with EventLoop

Source: https://revolt.run/signals

Uses EventLoop::onSignal to handle SIGINT signals, allowing for graceful process termination.

```php
<?php

use Revolt\EventLoop;

// Let's tick off output once per second, so we can see activity.
EventLoop::repeat(1, function (): void {
    echo "tick: ", date('c'), "\n";
});

// What to do when a SIGINT signal is received
EventLoop::onSignal(SIGINT, function (): void {
    echo "Caught SIGINT! exiting ...\n";
    exit;
});

EventLoop::run();
```

--------------------------------

### Schedule a periodic callback

Source: https://revolt.run/timers

Schedules a callback to execute repeatedly at a fixed interval. Must be explicitly canceled to prevent memory leaks.

```php
<?php // using EventLoop::repeat()

use Revolt\EventLoop;

EventLoop::repeat(0.1, function ($callbackId): void {
    static $i = 0;

    if ($i++ < 3) {
        echo "tick\n";
    } else {
        EventLoop::cancel($callbackId);
    }
});

EventLoop::run();
```

--------------------------------

### Manage asynchronous execution with EventLoop suspension

Source: https://revolt.run/fundamentals

Demonstrates using EventLoop::getSuspension to pause script execution until a specific event resumes it.

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Revolt\EventLoop;

$suspension = EventLoop::getSuspension();

$repeatId = EventLoop::repeat(1, function (): void {
    print '++ Executing callback created by EventLoop::repeat()' . PHP_EOL;
});

EventLoop::delay(5, function () use ($suspension, $repeatId): void {
    print '++ Executing callback created by EventLoop::delay()' . PHP_EOL;

    EventLoop::cancel($repeatId);
    $suspension->resume(null);

    print '++ Suspension::resume() is async!' . PHP_EOL;
});

print '++ Suspending to event loop...' . PHP_EOL;

$suspension->suspend();

print '++ Script end' . PHP_EOL;
```

--------------------------------

### EventLoop::repeat()

Source: https://revolt.run/timers

Schedules a callback to repeatedly execute every n seconds.

```APIDOC
## EventLoop::repeat()

### Description
Schedules a callback to repeatedly execute every `n` seconds. Unlike other timers, these must be explicitly canceled to free resources.

### Callback Signature
`function (string $callbackId): void`
```

--------------------------------

### EventLoop::defer()

Source: https://revolt.run/timers

Schedules a callback to execute in the next iteration of the event loop, ensuring a clean call stack.

```APIDOC
## EventLoop::defer()

### Description
Schedules a callback to execute in the next iteration of the event loop. This method guarantees a clean call stack to avoid starvation of other events.

### Callback Signature
`function (string $callbackId)`
```

--------------------------------

### Schedule a deferred callback

Source: https://revolt.run/timers

Schedules a callback to execute in the next iteration of the event loop to ensure a clean call stack.

```php
<?php // using EventLoop::defer()

use Revolt\EventLoop;

echo "line 1\n";

EventLoop::defer(function (): void {
    echo "line 3\n";
});

echo "line 2\n";

EventLoop::run();
```

--------------------------------

### EventLoop::onSignal()

Source: https://revolt.run/signals

Registers a callback function to be executed when a specific signal is received by the process.

```APIDOC
## EventLoop::onSignal(int $signal, callable $callback)

### Description
Registers a callback to react to signals sent to the process. Signal callbacks can be enabled, disabled, and canceled like other event callbacks.

### Parameters
- **$signal** (int) - Required - The signal number to watch for (e.g., SIGINT).
- **$callback** (callable) - Required - The function to execute when the signal is received.

### Example
```php
use Revolt\EventLoop;

EventLoop::onSignal(SIGINT, function (): void {
    echo "Caught SIGINT! exiting ...\n";
    exit;
});
```
```

--------------------------------

### Self-cancellation of a callback

Source: https://revolt.run/fundamentals

Demonstrates that it is safe for a callback to cancel itself during execution.

```php
<?php

use Revolt\EventLoop;

$increment = 0;

EventLoop::repeat(0.1, function ($callbackId) use (&$increment): void {
    echo "tick\n";
    if (++$increment >= 3) {
        EventLoop::cancel($callbackId); // <-- cancel myself!
    }
});

EventLoop::run();
```

--------------------------------

### Schedule a delayed callback

Source: https://revolt.run/timers

Schedules a callback to execute after a specified number of seconds.

```php
<?php // using EventLoop::delay()

use Revolt\EventLoop;

EventLoop::delay(3, function (): void {
    print '3 seconds passed';
});

EventLoop::run();
```

--------------------------------

### EventLoop::delay()

Source: https://revolt.run/timers

Schedules a callback to execute after a specified delay in seconds.

```APIDOC
## EventLoop::delay()

### Description
Schedules a callback to execute after a delay of `n` seconds. The callback is automatically garbage collected after execution.

### Callback Signature
`function (string $callbackId)`
```

--------------------------------

### Cancel an event callback

Source: https://revolt.run/fundamentals

Demonstrates using EventLoop::cancel() to remove a persistent callback and prevent memory leaks.

```php
<?php

use Revolt\EventLoop;

$callbackId = EventLoop::repeat(1, function (): void {
    echo "tick\n";
});

// Cancel $callbackId in five seconds and exit the event loop
EventLoop::delay(5, function () use ($callbackId): void {
    EventLoop::cancel($callbackId);
});

EventLoop::run();
```

--------------------------------

### EventLoop::onWritable

Source: https://revolt.run/streams

Registers a callback to be invoked when a stream has buffer space available for writing.

```APIDOC
## EventLoop::onWritable

### Description
Registers a callback that is triggered when there is free space in the stream's write buffer. Note that streams are generally 'always' writable; this callback should be enabled only when there is data pending to be written to avoid high CPU usage.

### Signature
`EventLoop::onWritable(resource $socket, callable $callback): string`

### Parameters
- **$socket** (resource) - The stream resource to monitor.
- **$callback** (callable) - The function to execute. Receives `(string $callbackId, resource $socket)` as arguments.

### Returns
- **string** - A unique callback identifier used for management (e.g., enabling/disabling/canceling).
```

--------------------------------

### Disable an event callback

Source: https://revolt.run/fundamentals

Demonstrates using EventLoop::disable() to prevent a scheduled callback from executing.

```php
<?php

use Revolt\EventLoop;

// Register a callback we'll disable
$callbackIdToDisable = EventLoop::delay(1, function (): void {
    echo "I'll never execute in one second because: disable()\n";
});

// Register a callback to perform the disable() operation
EventLoop::delay(0.5, function () use ($callbackIdToDisable) {
    echo "Disabling callback: ", $callbackIdToDisable, "\n";
    EventLoop::disable($callbackIdToDisable);
});

EventLoop::run();
```

--------------------------------

### EventLoop::onReadable

Source: https://revolt.run/streams

Registers a callback to be invoked when data is available to read on a stream or when the stream reaches EOF.

```APIDOC
## EventLoop::onReadable

### Description
Registers a callback that is triggered when a stream has data available to read or reaches EOF. This is a low-level API intended for building stream abstractions.

### Signature
`EventLoop::onReadable(resource $socket, callable $callback): string`

### Parameters
- **$socket** (resource) - The stream resource to monitor.
- **$callback** (callable) - The function to execute. Receives `(string $callbackId, resource $socket)` as arguments.

### Returns
- **string** - A unique callback identifier used for management (e.g., cancellation).
```
Tokens:
Raw