Swoole\Coroutine — Klasse · PHP-Referenz

Signatur

class Swoole\Coroutine

Beschreibung

Swoole\Coroutine ist die zentrale Klasse des Swoole-Frameworks zur Verwaltung von Koroutinen. Koroutinen sind leichtgewichtige, kooperative Ausführungseinheiten, die es erlauben, asynchronen Code in einem synchronen, blockierend wirkenden Stil zu schreiben, ohne den gesamten Prozess zu blockieren. Intern verwendet Swoole einen Scheduler, der Koroutinen bei I/O-Operationen automatisch unterbricht und fortsetzt.

Typische Anwendungsfälle sind hochparallele Netzwerkserver, bei denen Tausende simultaner Verbindungen effizient verarbeitet werden müssen – etwa HTTP-Server, WebSocket-Server, Datenbank-Pools oder Message-Queue-Verbraucher. Im Vergleich zu Threads haben Koroutinen einen extrem geringen Overhead beim Context-Switch.

Die Klasse stellt sowohl statische Hilfsmethoden bereit (z. B. Coroutine::create(), Coroutine::getCid(), Coroutine::sleep()) als auch Methoden zur Steuerung einzelner Koroutinen-Instanzen. Koroutinen dürfen nur innerhalb eines Swoole-Eventloops (z. B. innerhalb von Swoole\Server-Callbacks oder Co\run()) genutzt werden.

Seit Swoole 4.x kann der Alias Co statt Swoole\Coroutine verwendet werden. Viele Funktionen aus der PHP-Standardbibliothek (z. B. file_get_contents, sleep, PDO) werden durch Coroutine-Hooks automatisch kooperativ gemacht, wenn Co::set(['hook_flags' => SWOOLE_HOOK_ALL]) aktiviert ist.

Parameter

Name	Typ	Default	Beschreibung
$callable Pflicht	callable		Die Callable (Closure, Funktionsname oder Methoden-Array), die in der neuen Koroutine ausgeführt wird. Wird an `Coroutine::create()` bzw. den Konstruktor übergeben.
$...$args	mixed		Beliebige zusätzliche Argumente, die an die Callable der Koroutine weitergegeben werden.

Rückgabewert

Typ

Beispiele

Einfache Koroutine mit Co\run()

<?php
use Swoole\Coroutine as Co;

Co\run(function () {
    $cid = Co::getCid();
    echo "Koroutine-ID: {$cid}\n";

    // Nicht-blockierendes Schlafen (gibt Kontrolle an Scheduler ab)
    Co::sleep(0.5);

    echo "Nach 0.5 Sekunden fortgesetzt\n";
});

Koroutine-ID: 1 Nach 0.5 Sekunden fortgesetzt

Mehrere parallele Koroutinen mit HTTP-Requests

<?php
use Swoole\Coroutine as Co;
use Swoole\Coroutine\Http\Client;

Co\run(function () {
    $urls = [
        'httpbin.org' => '/get',
        'example.com' => '/'
    ];

    $results = [];

    // Beide Requests starten gleichzeitig (WaitGroup)
    $wg = new Co\WaitGroup();

    foreach ($urls as $host => $path) {
        $wg->add();
        Co::create(function () use ($host, $path, &$results, $wg) {
            $client = new Client($host, 80);
            $client->get($path);
            $results[$host] = $client->statusCode;
            $client->close();
            $wg->done();
        });
    }

    $wg->wait();

    foreach ($results as $host => $status) {
        echo "{$host}: HTTP {$status}\n";
    }
});

httpbin.org: HTTP 200 example.com: HTTP 200

Coroutine-Hooks aktivieren für transparente Asynchronität

<?php
use Swoole\Coroutine as Co;

// Alle unterstützten PHP-Funktionen kooperativ machen
Co::set(['hook_flags' => SWOOLE_HOOK_ALL]);

Co\run(function () {
    // file_get_contents blockiert jetzt NICHT mehr den Prozess
    $html = file_get_contents('http://example.com');
    echo 'Länge: ' . strlen($html) . ' Bytes' . PHP_EOL;

    // sleep() gibt die Kontrolle an andere Koroutinen ab
    sleep(1);
    echo 'Fertig!' . PHP_EOL;
});

Länge: 1256 Bytes Fertig!

// Wichtig · Fallstricke

Nur innerhalb eines Eventloops verwenden: Koroutinen können ausschließlich innerhalb von Co\run(), Swoole-Server-Callbacks oder anderen Koroutinen-Kontexten erstellt werden. Ein Aufruf außerhalb führt zu einem fatalen Fehler.

Blocking-Operationen vermeiden: Klassische blockierende PHP-Operationen (z. B. mysqli_query() ohne Hook, sleep() ohne Hook) blockieren den gesamten Eventloop und heben den Parallelitätsvorteil auf. Immer Swoole-native Clients oder aktivierte Hooks (SWOOLE_HOOK_ALL) verwenden.

Shared State und Race Conditions: Obwohl Koroutinen im selben Prozess und Thread laufen, können durch kooperatives Scheduling unerwartete Zustandsänderungen auftreten. Zugriff auf gemeinsam genutzte Variablen sollte mit Swoole\Coroutine\Channel oder Co\WaitGroup koordiniert werden.

Swoole muss als PHP-Extension installiert sein: Swoole\Coroutine ist kein Bestandteil der PHP-Standardbibliothek, sondern erfordert die PECL-Extension swoole (mindestens Version 4.0). Die Klasse steht nicht in Standard-PHP-Umgebungen zur Verfügung.

Siehe auch

Swoole\Coroutine\Channel Swoole\Coroutine\WaitGroup Swoole\Coroutine\Http\Client Swoole\Server Swoole\Coroutine\Scheduler