Fibers

suggest change

A fiber (PHP 8.1) is a function that can pause itself in the middle and be continued later. It has its own call stack, so it can pause from anywhere: deep inside nested calls, or inside a callback called by array_map(). While it is paused, the code that started it keeps running.

Fibers don't run in parallel. There is still one thread, and only one fiber runs at a time. A fiber runs until it suspends itself, and then control goes back to whoever started or resumed it. This is cooperative multitasking. It is the building block for running many I/O-bound tasks in a single PHP process: while one task waits for a socket, another one runs.

Method What it does
new Fiber(callable $fn) creates a fiber; nothing runs yet
$fiber->start(...$args) calls $fn(...$args) and runs it until the first suspend or return
Fiber::suspend($value = null) pauses the current fiber; $value is returned by start()/resume()
$fiber->resume($value = null) continues the fiber; $value becomes the result of Fiber::suspend()
$fiber->throw(Throwable $e) continues the fiber by throwing $e from Fiber::suspend()
$fiber->getReturn() the value the fiber's function returned
isStarted(), isSuspended(), isRunning(), isTerminated() the fiber's state
Fiber::getCurrent() the running fiber, or null in the main code

All examples were run with PHP 8.5.

A first fiber

<?php
$fiber = new Fiber(function (string $name): string {
    echo "  fiber: hello, $name\n";
    Fiber::suspend();
    echo "  fiber: resumed\n";
    Fiber::suspend();
    echo "  fiber: finishing\n";
    return "done";
});

echo "main: start\n";
$fiber->start('Ann');
echo "main: fiber is suspended\n";
$fiber->resume();
echo "main: suspended again\n";
$fiber->resume();
echo "main: terminated? ", var_export($fiber->isTerminated(), true), "\n";
echo "main: result = ", $fiber->getReturn(), "\n";

Output:

main: start
  fiber: hello, Ann
main: fiber is suspended
  fiber: resumed
main: suspended again
  fiber: finishing
main: terminated? true
main: result = done

Control moves back and forth: start() runs the fiber until the first Fiber::suspend(), which returns to the main code. Each resume() continues the fiber right after the Fiber::suspend() call where it stopped, with all local variables intact. When the function returns, the fiber is terminated and getReturn() gives its return value.

Passing values in both directions

Fiber::suspend($value) sends a value out: it becomes the return value of the start() or resume() call that ran the fiber. resume($value) sends a value in: it becomes the return value of Fiber::suspend() inside the fiber.

<?php
$fiber = new Fiber(function (int $start): int {
    $total = $start;
    while (true) {
        $n = Fiber::suspend($total);   // send $total out, receive $n back
        if ($n === null) {
            return $total;
        }
        $total += $n;
    }
});

$out = $fiber->start(10);       // runs until the first suspend
echo "after start: $out\n";
echo "after resume(5): ", $fiber->resume(5), "\n";
echo "after resume(7): ", $fiber->resume(7), "\n";
var_dump($fiber->resume(null)); // the fiber returns, so resume() gives null
echo "return value: ", $fiber->getReturn(), "\n";

Output:

after start: 10
after resume(5): 15
after resume(7): 22
NULL
return value: 22

When the fiber returns instead of suspending, start()/resume() return null. That's why you check isTerminated() and read the result with getReturn().

Suspending from anywhere in the call stack

This is what fibers can do and generators can't. Fiber::suspend() is a static method that suspends whatever fiber is running, no matter how deep in the call stack it is. The functions in between don't need to know about it:

<?php
// Ordinary functions. Nothing in their signatures says "async".
function nextLine(): string
{
    // Ask whoever runs this fiber for the next line of input.
    return Fiber::suspend('need-input');
}

function askName(): string
{
    $name = nextLine();
    return ucfirst(trim($name));
}

function greet(): string
{
    $first = askName();
    $last = askName();
    return "Hello, $first $last!";
}

$fiber = new Fiber(greet(...));
$request = $fiber->start();
$input = ['ada', 'lovelace'];
while (!$fiber->isTerminated()) {
    echo "fiber asked for: $request\n";
    $request = $fiber->resume(array_shift($input));
}
echo $fiber->getReturn(), "\n";

Output:

fiber asked for: need-input
fiber asked for: need-input
Hello, Ada Lovelace!

nextLine(), askName() and greet() are plain functions returning plain strings. Only the code at the top (the "driver") deals with the fiber.

The same program with generators needs yield at the bottom and yield from at every level above it, and every function must return a Generator:

<?php
function nextLine(): Generator
{
    return yield 'need-input';
}

function askName(): Generator
{
    $name = yield from nextLine();
    return ucfirst(trim($name));
}

function greet(): Generator
{
    $first = yield from askName();
    $last = yield from askName();
    return "Hello, $first $last!";
}

$gen = greet();
$input = ['ada', 'lovelace'];
for ($request = $gen->current(); $gen->valid(); $request = $gen->send(array_shift($input))) {
    echo "generator asked for: $request\n";
}
echo $gen->getReturn(), "\n";

Output:

generator asked for: need-input
generator asked for: need-input
Hello, Ada Lovelace!

This is known as the "function coloring" problem: once a low-level function becomes a generator, all its callers must become generators too. With fibers there's only one color.

A fiber can even suspend inside a callback called by a built-in function, which a generator can't do at all (you can't yield from inside the closure passed to array_map(), because that closure would become a generator itself):

<?php
// Suspending from inside a callback called by a built-in function.
$fiber = new Fiber(function (array $ids): array {
    return array_map(fn(int $id) => Fiber::suspend($id), $ids);
});

$id = $fiber->start([1, 2, 3]);
while (!$fiber->isTerminated()) {
    echo "lookup user $id\n";
    $id = $fiber->resume("user-$id");
}
print_r($fiber->getReturn());

Output:

lookup user 1
lookup user 2
lookup user 3
Array
(
    [0] => user-1
    [1] => user-2
    [2] => user-3
)

Fiber states and FiberError

A fiber is in one of four states: not started, running, suspended or terminated.

<?php
function state(Fiber $f): string
{
    return match (true) {
        !$f->isStarted() => 'not started',
        $f->isRunning() => 'running',
        $f->isSuspended() => 'suspended',
        $f->isTerminated() => 'terminated',
    };
}

$fiber = new Fiber(function () use (&$fiber) {
    echo "inside: ", state($fiber), "\n";
    Fiber::suspend();
});

echo "before start: ", state($fiber), "\n";
$fiber->start();
echo "after start: ", state($fiber), "\n";
$fiber->resume();
echo "after resume: ", state($fiber), "\n";

Output:

before start: not started
inside: running
after start: suspended
after resume: terminated

Calling a method in the wrong state throws FiberError:

<?php
$tests = [
    'suspend outside a fiber' => fn() => Fiber::suspend(),
    'resume before start' => fn() => (new Fiber(fn() => 1))->resume(),
    'start twice' => function () {
        $f = new Fiber(fn() => Fiber::suspend());
        $f->start();
        $f->start();
    },
    'resume a finished fiber' => function () {
        $f = new Fiber(fn() => 1);
        $f->start();
        $f->resume();
    },
    'getReturn while suspended' => function () {
        $f = new Fiber(fn() => Fiber::suspend());
        $f->start();
        $f->getReturn();
    },
    'resume itself' => function () {
        $f = new Fiber(function () use (&$f) { $f->resume(); });
        $f->start();
    },
];

foreach ($tests as $name => $test) {
    try {
        $test();
    } catch (FiberError $e) {
        printf("%-26s %s: %s\n", $name, get_class($e), $e->getMessage());
    }
}

Output:

suspend outside a fiber    FiberError: Cannot suspend outside of a fiber
resume before start        FiberError: Cannot resume a fiber that is not suspended
start twice                FiberError: Cannot start a fiber that has already been started
resume a finished fiber    FiberError: Cannot resume a fiber that is not suspended
getReturn while suspended  FiberError: Cannot get fiber return value: The fiber has not returned
resume itself              FiberError: Cannot resume a fiber that is not suspended

FiberError extends Error, not Exception. It is a bug in the code driving the fiber, not something to recover from.

Fiber::getCurrent() tells you whether code runs inside a fiber. Libraries use it to decide between suspending and blocking (the pool in Database connection pooling does this):

<?php
function where(): string
{
    $f = Fiber::getCurrent();
    return $f === null ? 'main' : 'fiber #' . spl_object_id($f);
}

echo where(), "\n";
$fiber = new Fiber(fn() => print(where() . "\n"));
$fiber->start();
echo where(), "\n";

Output:

main
fiber #1
main

Exceptions

Throwing into a fiber

$fiber->throw($e) resumes a suspended fiber, but instead of returning a value, the pending Fiber::suspend() call throws $e. A scheduler uses this to report failures to the waiting code: a timeout, a closed connection, a cancelled operation.

<?php
class TimeoutException extends Exception {}

$fiber = new Fiber(function (): string {
    try {
        echo "fiber: waiting for data\n";
        $data = Fiber::suspend();
        return "got $data";
    } catch (TimeoutException $e) {
        echo "fiber: caught ", $e->getMessage(), "\n";
        Fiber::suspend('cleaned up');   // a fiber can keep running after catching
        return 'gave up';
    }
});

$fiber->start();
// Instead of resuming with a value, make the pending suspend() throw.
$value = $fiber->throw(new TimeoutException('no data after 5s'));
echo "main: fiber suspended with '$value'\n";
$fiber->resume();
echo "main: ", $fiber->getReturn(), "\n";

Output:

fiber: waiting for data
fiber: caught no data after 5s
main: fiber suspended with 'cleaned up'
main: gave up

Like resume(), throw() returns the value of the fiber's next Fiber::suspend(), or null if the fiber finished.

Exceptions thrown out of a fiber

An uncaught exception inside a fiber terminates it and is rethrown from the start(), resume() or throw() call that ran it:

<?php
$fiber = new Fiber(function (): void {
    Fiber::suspend();
    throw new RuntimeException('disk full');
});

$fiber->start();            // fine, the fiber is suspended
try {
    $fiber->resume();       // the exception escapes from resume()
} catch (RuntimeException $e) {
    echo "caught: ", $e->getMessage(), "\n";
}
var_dump($fiber->isTerminated());

try {
    $fiber->getReturn();
} catch (FiberError $e) {
    echo $e->getMessage(), "\n";
}

Output:

caught: disk full
bool(true)
Cannot get fiber return value: The fiber threw an exception

Destroying a suspended fiber

A fiber that is suspended and never resumed is not leaked. When the last reference to it goes away, PHP unwinds its stack: finally blocks run and destructors of its local objects are called. catch blocks don't run.

<?php
$fiber = new Fiber(function (): void {
    $h = fopen('php://memory', 'w');
    try {
        echo "fiber: working\n";
        Fiber::suspend();
        echo "fiber: never printed\n";
    } finally {
        fclose($h);
        echo "fiber: finally ran, handle closed\n";
    }
});
$fiber->start();
echo "main: dropping the suspended fiber\n";
unset($fiber);
echo "main: end\n";

Output:

fiber: working
main: dropping the suspended fiber
fiber: finally ran, handle closed
main: end

A minimal scheduler with stream_select

Fibers on their own don't do any I/O. To get concurrency you need a scheduler (an event loop): it keeps a list of fibers, knows what each one is waiting for, and resumes a fiber when its wait is over.

The scheduler below is about 100 lines. Tasks call delay(), waitReadable() or waitWritable(). Each of those calls Fiber::suspend() with a description of what to wait for, such as ['read', $stream]. The scheduler receives that value from start()/resume(), parks the fiber, and uses stream_select() to sleep until a stream is ready or the next timer is due.

Save this as scheduler.php:

<?php
// Functions that tasks call. Each one suspends the current fiber and tells
// the scheduler what the fiber is waiting for.
function delay(float $seconds): void
{
    Fiber::suspend(['delay', $seconds]);
}

/** @param resource $stream */
function waitReadable($stream): void
{
    Fiber::suspend(['read', $stream]);
}

/** @param resource $stream */
function waitWritable($stream): void
{
    Fiber::suspend(['write', $stream]);
}

final class Scheduler
{
    /** @var list<Fiber> fibers that can run right now */
    private array $ready = [];
    /** @var list<array{float, Fiber}> [wake-up time, fiber] */
    private array $timers = [];
    /** @var array<int, array{resource, Fiber}> */
    private array $readers = [];
    /** @var array<int, array{resource, Fiber}> */
    private array $writers = [];

    public function spawn(Closure $task): void
    {
        $this->ready[] = new Fiber($task);
    }

    public function run(): void
    {
        while ($this->ready || $this->timers || $this->readers || $this->writers) {
            $ready = $this->ready;
            $this->ready = [];
            foreach ($ready as $fiber) {
                $request = $fiber->isStarted() ? $fiber->resume() : $fiber->start();
                if (!$fiber->isTerminated()) {
                    $this->park($fiber, $request);
                }
            }
            $this->poll();
        }
    }

    private function park(Fiber $fiber, mixed $request): void
    {
        match ($request[0] ?? null) {
            'delay' => $this->timers[] = [microtime(true) + $request[1], $fiber],
            'read' => $this->readers[(int) $request[1]] = [$request[1], $fiber],
            'write' => $this->writers[(int) $request[1]] = [$request[1], $fiber],
            default => $this->ready[] = $fiber, // plain Fiber::suspend(): just yield
        };
    }

    private function poll(): void
    {
        // How long may we block? Not at all if something is ready,
        // until the next timer if there are timers, forever otherwise.
        $timeout = null;
        if ($this->ready) {
            $timeout = 0.0;
        } elseif ($this->timers) {
            $next = min(array_column($this->timers, 0));
            $timeout = max(0.0, $next - microtime(true));
        }

        if ($this->readers || $this->writers) {
            $r = array_column($this->readers, 0);
            $w = array_column($this->writers, 0);
            $e = null;
            $sec = $timeout === null ? null : (int) $timeout;
            $usec = $timeout === null ? null : (int) (($timeout - (int) $timeout) * 1e6);
            if (stream_select($r, $w, $e, $sec, $usec) > 0) {
                foreach ($r as $s) {
                    $this->ready[] = $this->readers[(int) $s][1];
                    unset($this->readers[(int) $s]);
                }
                foreach ($w as $s) {
                    $this->ready[] = $this->writers[(int) $s][1];
                    unset($this->writers[(int) $s]);
                }
            }
        } elseif ($timeout > 0) {
            usleep((int) ($timeout * 1e6));
        }

        $now = microtime(true);
        foreach ($this->timers as $i => [$wakeAt, $fiber]) {
            if ($wakeAt <= $now) {
                $this->ready[] = $fiber;
                unset($this->timers[$i]);
            }
        }
    }
}

Concurrent timers

Three tasks that each wait 3 times. Run one after another, they would take 0.9 + 1.5 + 0.6 = 3.0 seconds:

<?php
require __DIR__ . '/scheduler.php';

$t0 = microtime(true);
function say(string $msg): void
{
    global $t0;
    printf("[%.2fs] %s\n", microtime(true) - $t0, $msg);
}

$scheduler = new Scheduler();
foreach (['A' => 0.3, 'B' => 0.5, 'C' => 0.2] as $name => $interval) {
    $scheduler->spawn(function () use ($name, $interval) {
        for ($i = 1; $i <= 3; $i++) {
            delay($interval);
            say("task $name tick $i");
        }
    });
}
$scheduler->run();
say('all done');

Output (timings vary slightly):

[0.22s] task C tick 1
[0.31s] task A tick 1
[0.47s] task C tick 2
[0.52s] task B tick 1
[0.62s] task A tick 2
[0.69s] task C tick 3
[0.94s] task A tick 3
[1.04s] task B tick 2
[1.59s] task B tick 3
[1.59s] all done

The ticks interleave, and the whole run takes as long as the slowest task.

An echo server and its clients in one process

Now real I/O: a TCP server that upper-cases what it receives, and three clients talking to it at the same time. The server, each server-side connection and each client are separate fibers in the same process. The streams are non-blocking, and every fiber calls waitReadable()/waitWritable() before touching a stream, so no one blocks the others.

<?php
require __DIR__ . '/scheduler.php';

$scheduler = new Scheduler();

// Port 0: let the OS pick a free port.
$server = stream_socket_server('tcp://127.0.0.1:0', $errno, $errstr);
stream_set_blocking($server, false);
$address = stream_socket_get_name($server, false);
echo "listening on a random port\n";

$clients = 3;

// Server task: accept connections, one new fiber per connection.
$scheduler->spawn(function () use ($server, $scheduler, $clients) {
    for ($i = 1; $i <= $clients; $i++) {
        waitReadable($server);                 // a connection is pending
        $conn = stream_socket_accept($server, 0);
        stream_set_blocking($conn, false);
        $scheduler->spawn(function () use ($conn, $i) {
            while (true) {
                waitReadable($conn);
                $data = fread($conn, 8192);
                if ($data === '' || $data === false) {   // client closed
                    echo "server: connection $i closed\n";
                    fclose($conn);
                    return;
                }
                waitWritable($conn);
                fwrite($conn, strtoupper($data));
            }
        });
    }
    // Accepted all expected clients; the listening socket is closed at the end.
});

// Client tasks: each sends a few messages, pausing between them.
foreach (['ann' => 0.30, 'bob' => 0.20, 'cid' => 0.25] as $name => $pause) {
    $scheduler->spawn(function () use ($address, $name, $pause) {
        $sock = stream_socket_client("tcp://$address");
        stream_set_blocking($sock, false);
        foreach (['hello', 'how are you', 'bye'] as $msg) {
            fwrite($sock, "$name: $msg");
            waitReadable($sock);
            echo "client $name got: ", fread($sock, 8192), "\n";
            delay($pause);
        }
        fclose($sock);
    });
}

$start = microtime(true);
$scheduler->run();
printf("finished in %.1fs\n", microtime(true) - $start);
fclose($server);

Output:

listening on a random port
client ann got: ANN: HELLO
client bob got: BOB: HELLO
client cid got: CID: HELLO
client bob got: BOB: HOW ARE YOU
client cid got: CID: HOW ARE YOU
client ann got: ANN: HOW ARE YOU
client bob got: BOB: BYE
client cid got: CID: BYE
server: connection 2 closed
client ann got: ANN: BYE
server: connection 3 closed
server: connection 1 closed
finished in 0.9s

Each client pauses 0.6 to 0.9 seconds in total, and everything finishes in 0.9 seconds: while one fiber waits, the others run. Notice that the client and server code reads top to bottom like blocking code. There are no callbacks or promises: waiting is just a function call that happens to suspend.

This scheduler is only for learning. It doesn't handle connection errors, timeouts or cancellation, and two fibers can't wait on the same stream. That is the job of an event-loop library.

Fibers in practice: Revolt, Amp and ReactPHP

The Fiber RFC was written by the authors of Amp, and the API is meant to be low level: application code is not supposed to create fibers or call Fiber::suspend() itself. In practice you use fibers through a library:

With Amp v3 (composer require amphp/amp), concurrent code looks like this:

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

use function Amp\async;
use function Amp\delay;
use function Amp\Future\await;

function fetchUser(int $id): string
{
    delay(0.5);               // suspends this fiber only, not the whole script
    return "user-$id";
}

$start = microtime(true);
$futures = [];
foreach ([1, 2, 3] as $id) {
    $futures[$id] = async(fetchUser(...), $id);  // each call runs in its own fiber
}
print_r(await($futures));     // wait for all of them
printf("took %.1fs\n", microtime(true) - $start);

Output:

Array
(
    [1] => user-1
    [2] => user-2
    [3] => user-3
)
took 0.5s

Three half-second waits take half a second in total. async() runs a function in a new fiber, and await() suspends until the futures complete. When called from the main code (outside any fiber), it runs the event loop until then.

Under the hood, libraries do what our scheduler does. Revolt's EventLoop::getSuspension() returns an object that wraps Fiber::suspend()/resume() for the current fiber, and event-loop callbacks resume it:

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

use Revolt\EventLoop;

// What Amp's delay() does inside: park the current fiber in a Suspension
// and let an event-loop timer resume it.
function sleepFor(float $seconds): void
{
    $suspension = EventLoop::getSuspension();
    EventLoop::delay($seconds, fn() => $suspension->resume());
    $suspension->suspend();
}

/** @param resource $stream */
function readWhenReady($stream): string
{
    $suspension = EventLoop::getSuspension();
    $id = EventLoop::onReadable($stream, function (string $id) use ($suspension, $stream) {
        EventLoop::cancel($id);
        $suspension->resume(fread($stream, 8192));
    });
    return $suspension->suspend();
}

[$a, $b] = stream_socket_pair(STREAM_PF_INET, STREAM_SOCK_STREAM, STREAM_IPPROTO_IP);
stream_set_blocking($b, false);

EventLoop::queue(function () use ($a) {
    sleepFor(0.2);
    fwrite($a, "ping");
});

echo "waiting...\n";
echo "got: ", readWhenReady($b), "\n";   // the main code can suspend too

Output:

waiting...
got: ping

Revolt also lets the main code suspend (it runs the loop in that case), which plain Fiber::suspend() can't do.

Old Amp v2 and earlier code used generators as coroutines, with yield for every await. You will see that style in Using Amp event loop. Amp v3 replaced it with fibers. For timeouts and Cancellation objects in Amp v3 see Cancellation and timeouts.

Fibers vs generators

Generators Fibers
Since PHP 5.5 PHP 8.1
Pause with yield keyword, only in the generator function itself Fiber::suspend(), from any depth of the call stack
Effect on callers every caller must be a generator (yield from) callers are ordinary functions
Inside callbacks of array_map() etc. not possible possible
Stack none of its own; a generator is one paused function frame its own full call stack
Iterable with foreach yes no
Typical use lazy sequences, streaming large data, pipelines concurrency: event loops, async I/O libraries

Use generators for producing values lazily (see Advantages of Generators and Using the send function to pass values to a generator). Use fibers, usually through a library, for running many waiting tasks at once.

Pitfalls

Blocking calls block everything. A fiber is not a thread. sleep(), file_get_contents() on a URL, a PDO query or a cURL request inside a fiber freeze the whole process until they finish:

<?php
$fiber = new Fiber(function (): void {
    echo "fiber: blocking sleep for 1s...\n";
    sleep(1);                // blocks the whole process, not just this fiber
    echo "fiber: done\n";
});
$start = microtime(true);
$fiber->start();
printf("main: got control back after %.1fs\n", microtime(true) - $start);

Output:

fiber: blocking sleep for 1s...
fiber: done
main: got control back after 1.0s

Concurrency only happens when the waiting goes through the event loop, so you need non-blocking drivers (for example amphp/mysql instead of PDO). For running blocking work alongside, see Spawning non-blocking processes with proc_open.

Shared state. Fibers don't run in parallel, so there are no data races in the threading sense. But any function that might suspend is a point where other fibers run and change shared objects. Re-check state after a call that can wait, just like after an await in JavaScript.

Memory. Each fiber has its own PHP VM stack (counted in memory_limit) and a native C stack whose size is set by the fiber.stack_size ini setting:

<?php
$fibers = [];
$mem = memory_get_usage();
$start = microtime(true);
for ($i = 0; $i < 1000; $i++) {
    $f = new Fiber(fn() => Fiber::suspend());
    $f->start();
    $fibers[] = $f;
}
printf("1000 suspended fibers: %.0f ms, %.0f KB of PHP memory each\n",
    (microtime(true) - $start) * 1000, (memory_get_usage() - $mem) / 1000 / 1024);

Output:

1000 suspended fibers: 9 ms, 17 KB of PHP memory each

Thousands of fibers are fine; millions are not.

Debuggers and profilers need fiber support. Recent versions of Xdebug and most APM extensions have it, but old versions can crash or show confusing stack traces.

Summary

Feedback about page:

Feedback:
Optional: your email if you want me to get back to you:



Table Of Contents