eio_write — Funktion · PHP-Referenz

Signatur

eio_write(mixed $fd, string $str, int $length = 0, int $offset = 0, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

Beschreibung

eio_write() ist Teil der eio-Erweiterung, die asynchrone I/O-Operationen auf Basis der libeio-Bibliothek bereitstellt. Die Funktion schreibt $length Bytes aus dem String $str an die Position $offset des gegebenen Dateideskriptors, ohne den laufenden PHP-Prozess zu blockieren.

Der Schreibvorgang wird in einem internen Thread-Pool durchgeführt. Sobald er abgeschlossen ist, wird die Callback-Funktion aufgerufen und liefert Informationen über den Erfolg oder Misserfolg der Operation. Dies eignet sich besonders für ereignisgesteuerte Architekturen, z. B. in Verbindung mit libevent oder ReactPHP-ähnlichen Event-Loops.

Die Funktion gibt eine resource zurück, die den ausstehenden Auftrag repräsentiert und z. B. mit eio_cancel() abgebrochen werden kann. Der Dateideskriptor $fd muss zuvor mit eio_open() oder einer anderen kompatiblen Funktion geöffnet worden sein.

Typische Einsatzszenarien sind Hochlast-Server-Applikationen, Log-Writer oder andere Szenarien, in denen blockierende Dateizugriffe die Performance beeinträchtigen würden.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Dateideskriptor, der mit `eio_open()` oder einer kompatiblen Funktion geöffnet wurde. Kann ein Integer (nativer Dateideskriptor) oder eine `eio`-Ressource sein.
$str Pflicht	string		Der zu schreibende Inhalt als PHP-String.
$length	int	0	Anzahl der zu schreibenden Bytes. Wird `0` übergeben, wird die gesamte Länge von `$str` verwendet.
$offset	int	0	Byte-Offset innerhalb der Datei, ab dem geschrieben werden soll. Der Wert `0` bedeutet den Anfang der Datei.
$pri	int	EIO_PRI_DEFAULT	Priorität des Auftrags. Gültige Werte sind `EIO_PRI_MIN`, `EIO_PRI_DEFAULT` und `EIO_PRI_MAX`.
$callback	callable	NULL	Callback-Funktion, die nach Abschluss des Schreibvorgangs aufgerufen wird. Signatur: `function(mixed $data, int $result, resource $req): void`. `$result` enthält die Anzahl geschriebener Bytes oder `-1` bei einem Fehler.
$data	mixed	NULL	Beliebige benutzerdefinierte Daten, die unverändert an den `$callback` weitergegeben werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt eine eio-Auftrags-Ressource zurück, die den asynchronen Schreibauftrag repräsentiert. Diese Ressource kann mit eio_cancel() abgebrochen werden. Bei einem Fehler wird false zurückgegeben.

Beispiele

Einfaches asynchrones Schreiben in eine Datei

<?php
// eio-Event-Loop wird benötigt
eio_init();

$path = '/tmp/eio_test.txt';

// Datei öffnen (asynchron)
eio_open(
    $path,
    EIO_O_WRONLY | EIO_O_CREAT | EIO_O_TRUNC,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result === -1) {
            echo "Fehler beim Öffnen: " . eio_get_last_error($req) . PHP_EOL;
            return;
        }

        $fd = $result;
        $content = "Hallo, asynchrone Welt!";

        // Asynchron schreiben
        eio_write(
            $fd,
            $content,
            strlen($content),
            0,
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd) {
                if ($result === -1) {
                    echo "Fehler beim Schreiben: " . eio_get_last_error($req) . PHP_EOL;
                } else {
                    echo "Bytes geschrieben: " . $result . PHP_EOL;
                }
                // Datei schließen
                eio_close($fd);
            }
        );
    }
);

// Event-Loop starten
eio_event_loop();

Bytes geschrieben: 23

Schreiben mit benutzerdefinierten Daten im Callback

<?php
eio_init();

$path = '/tmp/eio_log.txt';
$meta = ['job_id' => 42, 'user' => 'admin'];

eio_open(
    $path,
    EIO_O_WRONLY | EIO_O_CREAT | EIO_O_APPEND,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $fd, $req) use ($meta) {
        if ($fd === -1) {
            echo "Datei konnte nicht geöffnet werden." . PHP_EOL;
            return;
        }

        $logLine = sprintf(
            "[Job %d] User: %s — Aktion gespeichert\n",
            $meta['job_id'],
            $meta['user']
        );

        eio_write(
            $fd,
            $logLine,
            0,       // gesamte Länge
            0,
            EIO_PRI_DEFAULT,
            function ($cbData, $result, $req) use ($fd) {
                echo "Log-Eintrag geschrieben: {$result} Bytes (Job-ID: {$cbData['job_id']})" . PHP_EOL;
                eio_close($fd);
            },
            $meta    // wird als $cbData an den Callback übergeben
        );
    }
);

eio_event_loop();

Log-Eintrag geschrieben: 43 Bytes (Job-ID: 42)

// Wichtig · Fallstricke

Achtung: Die eio-Erweiterung ist nicht standardmäßig in PHP enthalten und muss explizit installiert werden (pecl install eio). Sie ist unter Windows nicht verfügbar.

Der Dateideskriptor darf nicht geschlossen werden, solange der asynchrone Schreibauftrag noch aussteht, da dies zu undefiniertem Verhalten oder Datenverlust führen kann. Das Schließen sollte stets im Callback erfolgen.

Fehler lassen sich im Callback über eio_get_last_error($req) ermitteln. Ein Rückgabewert von -1 in $result zeigt stets einen Fehler an.

Die Funktion eignet sich nicht für den Einsatz in einfachen synchronen Skripten; sie entfaltet ihren Nutzen ausschließlich in einem Event-Loop-Kontext.

Siehe auch

eio_open eio_read eio_close eio_cancel eio_get_last_error eio_event_loop