swoole_async_read — Funktion · PHP-Referenz

Signatur

swoole_async_read(string $filename, callable $callback, int $chunk_size = 65536, int $offset = 0): bool

Beschreibung

swoole_async_read ist eine Funktion der Swoole-Erweiterung und ermöglicht das nicht-blockierende, asynchrone Lesen einer Datei. Anstatt auf das vollständige Einlesen zu warten, kehrt die Funktion sofort zurück und ruft den angegebenen Callback auf, sobald ein Datenteil (Chunk) eingelesen wurde. So wird der PHP-Prozess nicht blockiert und kann in dieser Zeit andere Aufgaben erledigen.

Der Callback wird für jeden gelesenen Chunk aufgerufen und erhält den Dateinamen sowie den gelesenen Inhalt als Parameter. Ist der gesamte Dateiinhalt gelesen, wird der Callback ein letztes Mal mit einem leeren String aufgerufen, was das Ende des Lesevorgangs signalisiert. Gibt der Callback false zurück, wird der Lesevorgang vorzeitig abgebrochen.

Diese Funktion ist besonders sinnvoll in Swoole-basierten Servern oder Event-Loop-Anwendungen, wo synchrones Blockieren des Prozesses (z. B. durch file_get_contents) unerwünscht ist und die Performance bei der Verarbeitung großer Dateien oder vieler gleichzeitiger Anfragen verbessert werden soll.

Hinweis: swoole_async_read wurde in neueren Swoole-Versionen (ab 4.x) als veraltet markiert und durch Coroutine-basierte Alternativen wie Swoole\Coroutine\System::readFile() ersetzt. In aktuellen Projekten sollten coroutinebasierte Ansätze bevorzugt werden.

Parameter

Name	Typ	Default	Beschreibung
$filename Pflicht	string		Der vollständige Pfad zur Datei, die asynchron gelesen werden soll.
$callback Pflicht	callable		Callback-Funktion, die für jeden eingelesenen Chunk aufgerufen wird. Signatur: `function(string $filename, string $content): bool\|void`. Gibt der Callback `false` zurück, wird der Lesevorgang abgebrochen. Ein leerer `$content`-String signalisiert das Ende der Datei.
$chunk_size	int	65536	Größe eines einzelnen Datenblocks in Bytes, der pro Callback-Aufruf eingelesen wird. Standardmäßig 64 KB (65536 Bytes).
$offset	int	0	Byte-Offset, ab dem das Lesen der Datei beginnen soll. Standardmäßig 0 (Dateianfang).

Rückgabewert

Typ

bool

Beschreibung

Gibt true zurück, wenn die asynchrone Leseoperation erfolgreich eingeleitet wurde, andernfalls false (z. B. wenn die Datei nicht gefunden wurde oder kein Swoole-Event-Loop aktiv ist).

Beispiele

Einfaches asynchrones Lesen einer Datei

<?php
// Swoole-Server oder Event-Loop vorausgesetzt
swoole_async_read('/var/log/app.log', function(string $filename, string $content): bool {
    if ($content === '') {
        // Datei vollständig gelesen
        echo "Lesen von '{$filename}' abgeschlossen." . PHP_EOL;
        return true;
    }
    echo "Chunk empfangen (" . strlen($content) . " Bytes): " . substr($content, 0, 80) . PHP_EOL;
    return true; // Weiterlesen
}, 4096);

Chunk empfangen (4096 Bytes): ... Lesen von '/var/log/app.log' abgeschlossen.

Lesevorgang vorzeitig abbrechen

<?php
// Lesen nur des ersten Chunks und dann Abbruch
$maxBytes = 1024;
swoole_async_read('/pfad/zur/datei.txt', function(string $filename, string $content) use ($maxBytes): bool {
    if ($content === '') {
        echo "Fertig." . PHP_EOL;
        return true;
    }
    echo "Erster Chunk eingelesen: " . strlen($content) . " Bytes" . PHP_EOL;
    // Abbruch nach erstem Chunk durch Rückgabe von false
    return false;
}, $maxBytes);

Erster Chunk eingelesen: 1024 Bytes

Lesen ab einem bestimmten Offset

<?php
// Datei ab Byte 512 lesen (z. B. um einen Header zu überspringen)
swoole_async_read('/pfad/zur/binary.dat', function(string $filename, string $content): bool {
    if ($content === '') {
        echo "Lesen abgeschlossen." . PHP_EOL;
        return true;
    }
    // Inhalt verarbeiten
    echo "Daten empfangen ab Offset 512: " . bin2hex(substr($content, 0, 8)) . PHP_EOL;
    return true;
}, 65536, 512);

Daten empfangen ab Offset 512: 4d5a9000030000000 Lesen abgeschlossen.

// Wichtig · Fallstricke

Deprecation: swoole_async_read ist seit Swoole 4.x veraltet (deprecated) und wird in zukünftigen Versionen möglicherweise entfernt. Für neue Projekte wird empfohlen, stattdessen die Coroutine-API zu verwenden: Swoole\Coroutine\System::readFile() oder Swoole\Coroutine\run() mit dateibasierten Coroutine-Operationen.

Voraussetzung: Die Funktion erfordert einen aktiven Swoole-Event-Loop. Außerhalb eines Swoole-Servers oder ohne laufenden Event-Loop (z. B. in einem normalen CLI-Skript ohne Swoole\Event::wait()) funktioniert die asynchrone Verarbeitung nicht korrekt.

Fehlerbehandlung: Prüfe immer den Rückgabewert von swoole_async_read, um sicherzustellen, dass die Operation erfolgreich gestartet wurde. Fehler bei nicht vorhandenen Dateien werden nicht als Exception geworfen, sondern führen zu einem false-Rückgabewert.

Siehe auch

swoole_async_write Swoole\Coroutine\System::readFile Swoole\Event::wait file_get_contents fread