Fibers
suggest changeA 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:
- Revolt is a shared event loop for fibers. It manages timers and stream watchers and gives you a
Suspensionobject to wait on. Amp v3 is built on it, and an adapter lets ReactPHP code run on the same loop. - Amp v3 provides
async(), futures, cancellation, and non-blocking clients for HTTP, sockets, MySQL, PostgreSQL, Redis and more. - ReactPHP is callback and promise based, and its
react/asyncpackage uses fibers forawait().
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
- A fiber is a function with its own stack that can pause with
Fiber::suspend()and continue withresume(). - Values travel out with
Fiber::suspend($value)and in withresume($value).throw($e)makes the pending suspend throw. - Fibers can suspend from any depth and from inside callbacks, so ordinary functions stay ordinary. Generators can't do that.
- Calling a method in the wrong state throws
FiberError. Exceptions inside a fiber come out ofstart()/resume(). - A scheduler plus
stream_select()turns fibers into concurrent I/O, but in real code use Amp v3, Revolt or ReactPHP instead of creating fibers yourself. - Blocking functions still block the whole process.