Fiber Support

[EdmondDantes]

Today, the development of Fiber support has been completed.
I haven’t updated the RFC text yet, this will be done later, but here you can see a brief overview of the changes.

Concept

Fibers are considered not as a low-level primitive, but as stateful generator-like coroutines.

The following statements are true:

1. A Fiber is a coroutine
2. Fibers are symmetric
3. Fibers can suspend and wait for manual resumption (this is intentionally disallowed for coroutines)
4. $fiber->start() and $fiber->resume() are blocking methods. They block the execution of the coroutine that calls them.
5. Different coroutines can create different Fibers that are not symmetric with each other. In other words, symmetry is preserved only within a single execution flow.

1. Creating and Starting a Fiber in a Coroutine

Fibers are created inside coroutines and started with the start() method:

use function Async\spawn;
use function Async\await;

$coroutine = spawn(function() {
    $fiber = new Fiber(function() {
        echo "Fiber executing\n";
        return "fiber result";
    });
    
    $result = $fiber->start();
    echo "Fiber returned: " . $result . "\n";
    
    return "coroutine result";
});

await($coroutine);

2. Suspend and Resume

Fibers can suspend their execution and pass values outward:

$fiber = new Fiber(function() {
    echo "Before suspend\n";
    $value = Fiber::suspend("suspended");
    echo "After resume, got: " . $value . "\n";
    return "done";
});

$suspended = $fiber->start();  // Returns "suspended"
$result = $fiber->resume("resume value");  // Returns "done"

3. Multiple Suspend/Resume Cycles

A fiber can suspend multiple times:

$fiber = new Fiber(function() {
    $v1 = Fiber::suspend("suspend-1");
    $v2 = Fiber::suspend("suspend-2");
    $v3 = Fiber::suspend("suspend-3");
    return "final";
});

$fiber->start();           // Returns "suspend-1"
$fiber->resume("data-1");  // Returns "suspend-2"
$fiber->resume("data-2");  // Returns "suspend-3"
$fiber->resume("data-3");  // Returns "final"

4. Different coroutines can be suspended by different Fibers.

$fiberA = new Fiber(function () {
    // Fiber A suspends coroutine A
    Fiber::suspend('A-1');
});

$fiberB = new Fiber(function () {
    // Fiber B suspends coroutine B
    Fiber::suspend('B-1');
});

spawn(function () use ($fiberA) {
    $fiberA->start();                     // suspends coroutine A
});

spawn(function () use ($fiberB) {
    $fiberB->start();                     // suspends coroutine B
});

5. Fibers receive an additional getCoroutine() method, which returns the coroutine instance.

$fiber = new Fiber(function() {
    return "final";
});

$fiber->start();
echo $fiber->getCoroutine()->getId();