Scope: Verwaltung von Coroutine-Lebenszyklen ​

function processUser($userId) {
    spawn(sendEmail(...), $userId);
    spawn(updateCache(...), $userId);
    spawn(logActivity(...), $userId);

    return "OK";
}

processUser(123);
// Die Funktion hat zurückgegeben, aber drei Coroutinen laufen noch!
// Wer überwacht sie? Wann werden sie fertig?
// Wer behandelt Ausnahmen, wenn sie auftreten?

function processUser($userId):string {
    spawn(sendEmail(...), $userId);
    spawn(updateCache(...), $userId);
    spawn(logActivity(...), $userId);

    // Warte, bis alle Coroutinen im Scope abgeschlossen sind
    $scope->awaitCompletion(Async\timeout(1000));

    return "OK";
}

$scope = new Async\Scope();
$scope->spawn(processUser(...), 123);
$scope->awaitCompletion(Async\timeout(5000));

// Jetzt gibt die Funktion erst zurück, wenn ALLE Coroutinen abgeschlossen sind

class UserService
{
    // Nur ein einzigartiges Objekt besitzt einen einzigartigen Scope
    // Coroutinen leben so lange wie das UserService-Objekt
    private Scope $scope;

    public function __construct() {
        // Erstelle eine Kuppel für alle Service-Coroutinen
        $this->scope = new Async\Scope();
    }

    public function sendNotification($userId) {
        // Starte eine Coroutine innerhalb unserer Kuppel
        $this->scope->spawn(function() use ($userId) {
            // Diese Coroutine ist an UserService gebunden
            sendEmail($userId);
        });
    }

    public function __destruct() {
        // Wenn das Objekt gelöscht wird, werden Ressourcen garantiert aufgeräumt
        // Alle Coroutinen darin werden automatisch abgebrochen
        $this->scope->dispose();
    }
}

$service = new UserService();
$service->sendNotification(123);
$service->sendNotification(456);

// Service löschen - alle seine Coroutinen werden automatisch abgebrochen
unset($service);

$mainScope = new Async\Scope();

$mainScope->spawn(function() {
    echo "Hauptaufgabe\n";

    // Erstelle einen untergeordneten Scope
    $childScope = Async\Scope::inherit();

    $childScope->spawn(function() {
        echo "Teilaufgabe 1\n";
    });

    $childScope->spawn(function() {
        echo "Teilaufgabe 2\n";
    });

    // Warte auf Abschluss der Teilaufgaben
    $childScope->awaitCompletion(Async\timeout(5000));

    echo "Alle Teilaufgaben erledigt\n";
});

$mainScope->awaitCompletion(Async\timeout(5000));

$scope = new Async\Scope();

$scope->spawn(function() {
    try {
        while (true) {
            echo "Arbeite...\n";
            Async\delay(1000);
        }
    } catch (Async\AsyncCancellation $e) {
        echo "Ich wurde abgebrochen!\n";
    }
});

$scope->spawn(function() {
    try {
        while (true) {
            echo "Arbeite ebenfalls...\n";
            Async\delay(1000);
        }
    } catch (Async\AsyncCancellation $e) {
        echo "Ich auch!\n";
    }
});

// Arbeitet 3 Sekunden lang
Async\delay(3000);

// Bricht ALLE Coroutinen im Scope ab
$scope->cancel();

// Beide Coroutinen erhalten AsyncCancellation

$scope = new Async\Scope();

// Fehlerhandler einrichten
$scope->setExceptionHandler(function (Async\Scope $scope, Async\Coroutine $coroutine, Throwable $e) {
    echo "Fehler im Scope: " . $e->getMessage() . "\n";
    // Kann protokolliert, an Sentry gesendet werden usw.
});

$scope->spawn(function() {
    throw new Exception("Etwas ist schiefgelaufen!");
});

$scope->spawn(function() {
    echo "Ich arbeite einwandfrei\n";
});

$scope->awaitCompletion(Async\timeout(5000));

// Ausgabe:
// Fehler im Scope: Etwas ist schiefgelaufen!
// Ich arbeite einwandfrei

$scope = new Async\Scope();

$scope->spawn(function() {
    try {
        echo "Starte Arbeit\n";
        Async\delay(10000); // Lange Operation
        echo "Fertig\n"; // Wird nicht ausgeführt
    } finally {
        // Dies wird GARANTIERT ausgeführt
        echo "Räume Ressourcen auf\n";
        closeConnection();
    }
});

Async\delay(1000);
$scope->cancel(); // Abbruch nach einer Sekunde

// Ausgabe:
// Starte Arbeit
// Räume Ressourcen auf

$group = new Async\TaskGroup(concurrency: 5);

$group->spawn(fn() => fetchUser(1));
$group->spawn(fn() => fetchUser(2));
$group->spawn(fn() => fetchUser(3));

// Alle Ergebnisse abrufen (wartet auf Abschluss aller Aufgaben)
$results = await($group->all());

// Oder das erste abgeschlossene Ergebnis abrufen
$first = await($group->race());

// Oder das erste erfolgreiche (Fehler ignorierend)
$any = await($group->any());

$group = new Async\TaskGroup();

$group->spawnWithKey('user', fn() => fetchUser(1));
$group->spawnWithKey('orders', fn() => fetchOrders(1));

// Über Ergebnisse iterieren, sobald sie bereit sind
foreach ($group as $key => [$result, $error]) {
    if ($error) {
        echo "Aufgabe $key fehlgeschlagen: {$error->getMessage()}\n";
    } else {
        echo "Aufgabe $key: $result\n";
    }
}

// Auf oberster Ebene: Die Coroutine landet im globalen Scope
spawn(function() {
    echo "Ich bin im globalen Scope\n";
});

// Innerhalb einer Coroutine: Die Coroutine landet im Scope des Aufrufers
$scope = new Async\Scope();
$scope->spawn(function() {
    spawn(function() {
        echo "Ich bin in \$scope, genau wie mein Elternteil\n";
    });
});

class HttpClient {
    private Scope $scope;

    public function __construct() {
        $this->scope = new Async\Scope();
    }

    public function get(string $url): Async\Awaitable {
        return $this->scope->spawn(function() use ($url) {
            $ch = curl_init($url);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

            try {
                return curl_exec($ch);
            } finally {
                curl_close($ch);
            }
        });
    }

    public function cancelAll(): void {
        // Alle aktiven Anfragen abbrechen
        $this->scope->cancel();
    }

    public function __destruct() {
        // Wenn der Client zerstört wird, werden alle Anfragen automatisch abgebrochen
        $this->scope->dispose();
    }
}

$client = new HttpClient();

$req1 = $client->get('https://api1.com/data');
$req2 = $client->get('https://api2.com/data');
$req3 = $client->get('https://api3.com/data');

// Alle Anfragen abbrechen
$client->cancelAll();

// Oder einfach den Client zerstören - gleicher Effekt
unset($client);

$scope = new Async\Scope();
$scope->spawn(function() { /* Aufgabe 1 */ });
$scope->spawn(function() { /* Aufgabe 2 */ });

// Die Kontrolle wird erst zurückgegeben, wenn beide Aufgaben abgeschlossen sind
$scope->awaitCompletion(Async\timeout(5000));

$scope->cancel();
// Alle Coroutinen in $scope erhalten ein Abbruchsignal.
// Untergeordnete Scopes werden ebenfalls abgebrochen -- rekursiv, bis in jede Tiefe.

$scope->dispose();
// Scope ist geschlossen. Alle Coroutinen sind abgebrochen.
// Neue Coroutinen können nicht zu diesem Scope hinzugefügt werden.

$scope->disposeSafely();
// Scope ist geschlossen. Coroutinen arbeiten als Zombies weiter.
// Scope verfolgt sie, zählt sie aber nicht als aktiv.