eio_read — Funktion · PHP-Referenz

Signatur

eio_read(mixed $fd, int $length, int $offset, int $pri, callable $callback, mixed $data = NULL): resource

Beschreibung

eio_read() gehört zur eio-Erweiterung, die asynchrone POSIX-Datei-I/O-Operationen (basierend auf libeio) für PHP bereitstellt. Die Funktion liest eine bestimmte Anzahl von Bytes aus einem geöffneten Dateideskriptor, ohne den aktuellen PHP-Prozess zu blockieren. Die eigentliche Leseoperaion wird in einem Hintergrund-Thread ausgeführt; sobald sie abgeschlossen ist, wird $callback aufgerufen.

Der Parameter $offset gibt die Position innerhalb der Datei an, ab der gelesen werden soll. Im Gegensatz zu fread() verändert eio_read() den internen Datei-Zeiger nicht, da die Operation auf Dateideskriptor-Ebene stattfindet. Das macht sie besonders nützlich für wahlfreien Zugriff (Random Access) auf große Dateien.

Die Funktion wird typischerweise zusammen mit einer Event-Loop (z. B. libevent oder ReactPHP) eingesetzt, um hochperformante, nicht-blockierende Datei-E/A in Server-Applikationen zu realisieren. Die Callback-Funktion erhält als Argumente: den $data-Wert, den gelesenen String sowie den Anforderungs-Status.

Zu beachten ist, dass die eio-Erweiterung unter Windows nicht verfügbar ist und den Einsatz von eio_event_loop() oder einer integrierten Event-Loop erfordert, damit Callbacks tatsächlich ausgeführt werden.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Ein geöffneter Dateideskriptor (z. B. von `eio_open()` oder `fopen()` via `eio_get_fd_from_stream()`). Kann eine Ganzzahl (nativer Dateideskriptor) oder eine Stream-Ressource sein.
$length Pflicht	int		Anzahl der zu lesenden Bytes.
$offset Pflicht	int		Offset in der Datei, ab dem gelesen werden soll. `0` steht für den Dateianfang.
$pri Pflicht	int		Priorität der Anforderung. Einer der Werte `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX` oder `NULL` (entspricht `EIO_PRI_DEFAULT`).
$callback Pflicht	callable		Callback-Funktion mit der Signatur `callback(mixed $data, string $result, int $req)`. `$result` enthält die gelesenen Bytes als String, `$req` den Anforderungs-Status.
$data	mixed	NULL	Beliebige benutzerdefinierte Daten, die unverändert an die Callback-Funktion weitergegeben werden. Nützlich, um Kontext-Informationen zu übermitteln.

Rückgabewert

Typ

resource

Beschreibung

Gibt bei Erfolg eine eio_req-Ressource zurück, die die asynchrone Anforderung repräsentiert. Bei einem Fehler wird false zurückgegeben.

Beispiele

Datei asynchron lesen mit eio_read

<?php
// Benötigt die eio-Erweiterung

$tempFile = tempnam(sys_get_temp_dir(), 'eio_');
file_put_contents($tempFile, 'Hallo, asynchrone Welt!');

// Datei über eio_open asynchron öffnen
eio_open(
    $tempFile,
    EIO_O_RDONLY,
    0,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) use ($tempFile) {
        if ($result == -1) {
            echo "Fehler beim Öffnen: " . eio_get_last_error($req) . PHP_EOL;
            return;
        }

        $fd = $result;

        // 5 Bytes ab Offset 7 lesen ("asyn")
        eio_read(
            $fd,
            5,
            7,
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd, $tempFile) {
                echo "Gelesener Text: " . $result . PHP_EOL;

                // Dateideskriptor schließen
                eio_close($fd, EIO_PRI_DEFAULT, function () use ($tempFile) {
                    unlink($tempFile);
                });
            },
            null
        );
    },
    null
);

eio_event_loop();
?>

Gelesener Text: async

Kontextdaten an den Callback übergeben

<?php
// Beispiel: $data-Parameter für Kontext-Informationen nutzen

$tempFile = tempnam(sys_get_temp_dir(), 'eio_ctx_');
file_put_contents($tempFile, 'PHP eio ist leistungsstark!');

eio_open(
    $tempFile,
    EIO_O_RDONLY,
    0,
    EIO_PRI_DEFAULT,
    function ($data, $fd, $req) use ($tempFile) {
        if ($fd == -1) {
            echo "Datei konnte nicht geöffnet werden." . PHP_EOL;
            return;
        }

        $kontext = ['dateiname' => $tempFile, 'anfrage_id' => 42];

        eio_read(
            $fd,
            3,
            4,
            EIO_PRI_DEFAULT,
            function ($kontext, $inhalt, $req) use ($fd, $tempFile) {
                echo "Anfrage-ID: " . $kontext['anfrage_id'] . PHP_EOL;
                echo "Datei: " . $kontext['dateiname'] . PHP_EOL;
                echo "Inhalt (3 Bytes ab Offset 4): " . $inhalt . PHP_EOL;

                eio_close($fd, EIO_PRI_DEFAULT, function () use ($tempFile) {
                    unlink($tempFile);
                });
            },
            $kontext
        );
    },
    null
);

eio_event_loop();
?>

Anfrage-ID: 42 Datei: /tmp/eio_ctx_XXXXXX Inhalt (3 Bytes ab Offset 4): eio

// Wichtig · Fallstricke

Plattform: Die eio-Erweiterung ist nur unter Unix-ähnlichen Betriebssystemen (Linux, macOS) verfügbar. Unter Windows steht sie nicht zur Verfügung.

Event-Loop: Ohne einen expliziten Aufruf von eio_event_loop() oder die Integration in eine externe Event-Loop werden Callbacks nie ausgeführt. In produktiven Anwendungen sollte stattdessen eio_poll() zusammen mit einem Socket-Notifier verwendet werden.

Fehlerbehandlung: Wenn $result im Callback den Wert -1 enthält, ist ein Fehler aufgetreten. Der genaue Fehler kann über eio_get_last_error($req) abgerufen werden.

Speicher: Die gelesenen Daten werden als PHP-String im Callback übergeben. Bei sehr großen $length-Werten kann dies zu erheblichem Speicherverbrauch führen. Ressourcen sollten nach der Verwendung mit eio_close() freigegeben werden.

Siehe auch

eio_open eio_write eio_close eio_event_loop eio_poll eio_get_last_error