eio_fsync — Funktion · PHP-Referenz

Signatur

eio_fsync(mixed $fd, int $pri = EIO_PRI_DEFAULT, callable $callback = null, mixed $data = null): resource|false

Beschreibung

eio_fsync() ist Teil der eio-Erweiterung, die asynchrone POSIX-I/O-Operationen für PHP bereitstellt. Die Funktion entspricht dem systemnahen fsync(2)-Aufruf: Sie stellt sicher, dass alle im Kernel-Puffer gepufferten Schreibvorgänge für den angegebenen Datei-Deskriptor dauerhaft auf den Datenträger übertragen werden, bevor der Callback ausgeführt wird.

Gerade bei Anwendungen, bei denen Datenkonsistenz nach einem Systemabsturz kritisch ist (z. B. Datenbank-Journaling, Konfigurations-Persistenz), ist ein explizites Synchronisieren unerlässlich. Anders als das blockierende fsync() aus dem PHP-Kern gibt eio_fsync() sofort zurück und arbeitet im Hintergrund, sodass der Event-Loop nicht blockiert wird.

Der Callback erhält als ersten Parameter die an $data übergebenen Daten, als zweiten den Ergebnis-Code (0 bei Erfolg, -1 bei Fehler) und als dritten den eigentlichen Request. Die Funktion muss innerhalb eines laufenden eio-Event-Loops (z. B. eio_event_loop()) verwendet werden.

Hinweis: Der Datei-Deskriptor $fd muss eine via eio_open() oder eine kompatible Ressource geöffnete Datei sein, da eio intern mit nativen Datei-Deskriptoren arbeitet.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Der Datei-Deskriptor der zu synchronisierenden Datei. Typischerweise das Ergebnis einer `eio_open()`-Operation (ein Integer-Datei-Deskriptor oder eine kompatible eio-Ressource).
$pri	int	EIO_PRI_DEFAULT	Priorität der Anfrage. Mögliche Werte: `EIO_PRI_MIN`, `EIO_PRI_DEFAULT` oder `EIO_PRI_MAX`. Bestimmt die Reihenfolge, in der ausstehende eio-Anfragen abgearbeitet werden.
$callback	callable	null	Eine Callback-Funktion, die nach Abschluss des Vorgangs aufgerufen wird. Signatur: `function(mixed $data, int $result, resource $req): void`. `$result` ist 0 bei Erfolg und -1 bei einem Fehler.
$data	mixed	null	Beliebige benutzerdefinierte Daten, die unverändert als erster Parameter an den `$callback` weitergereicht werden. Nützlich, um Kontext-Informationen in den Callback zu transportieren.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt bei Erfolg eine eio-Anfrage-Ressource zurück, die z. B. mit eio_cancel() abgebrochen werden kann. Im Fehlerfall wird false zurückgegeben.

Beispiele

Datei öffnen, beschreiben und mit eio_fsync synchronisieren

<?php
// eio-Erweiterung wird benötigt
// Datei asynchron öffnen
eio_open(
    '/tmp/testdatei.txt',
    EIO_O_RDWR | EIO_O_CREAT | EIO_O_TRUNC,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        if ($result < 0) {
            echo "Fehler beim Öffnen: " . eio_get_last_error($req) . PHP_EOL;
            return;
        }
        $fd = $result;

        // Asynchron in die Datei schreiben
        eio_write(
            $fd,
            'Wichtige Daten, die persistent gespeichert werden müssen.',
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd) {
                if ($result < 0) {
                    echo "Fehler beim Schreiben." . PHP_EOL;
                    eio_close($fd);
                    return;
                }
                echo "Geschriebene Bytes: $result" . PHP_EOL;

                // Sicherstellen, dass die Daten auf dem Datenträger landen
                eio_fsync(
                    $fd,
                    EIO_PRI_DEFAULT,
                    function ($data, $result, $req) use ($fd) {
                        if ($result === 0) {
                            echo "fsync erfolgreich — Daten sind auf dem Datenträger." . PHP_EOL;
                        } else {
                            echo "fsync fehlgeschlagen." . PHP_EOL;
                        }
                        // Datei schließen
                        eio_close($fd);
                    }
                );
            }
        );
    }
);

// Event-Loop starten
eio_event_loop();
?>

Geschriebene Bytes: 55 fsync erfolgreich — Daten sind auf dem Datenträger.

Benutzer-Daten über den Callback weitergeben

<?php
$meta = ['dateiname' => '/tmp/log.txt', 'zeitstempel' => time()];

eio_open(
    $meta['dateiname'],
    EIO_O_RDWR | EIO_O_CREAT | EIO_O_TRUNC,
    0600,
    EIO_PRI_DEFAULT,
    function ($data, $fd, $req) {
        if ($fd < 0) {
            echo "Öffnen fehlgeschlagen." . PHP_EOL;
            return;
        }
        eio_write($fd, "Log-Eintrag\n", EIO_PRI_DEFAULT, function ($data, $result, $req) use ($fd) {
            eio_fsync(
                $fd,
                EIO_PRI_DEFAULT,
                function ($data, $result, $req) use ($fd) {
                    echo "Sync abgeschlossen für: " . $data['dateiname'] . PHP_EOL;
                    echo "Zeitstempel: " . date('Y-m-d H:i:s', $data['zeitstempel']) . PHP_EOL;
                    eio_close($fd);
                },
                $data // Meta-Daten werden weitergereicht
            );
        }, $data);
    },
    $meta
);

eio_event_loop();
?>

Sync abgeschlossen für: /tmp/log.txt Zeitstempel: 2024-01-15 10:30:00

// Wichtig · Fallstricke

Achtung: eio_fsync() ist nur verfügbar, wenn die eio-PECL-Erweiterung installiert ist. Sie ist nicht Teil der PHP-Standardinstallation und muss separat über PECL eingebunden werden.

Im Gegensatz zu eio_fdatasync() synchronisiert eio_fsync() sowohl die Nutzdaten als auch die Metadaten (z. B. Dateigrößen, Zeitstempel) der Datei. Ist nur die Datenkonsistenz erforderlich, kann eio_fdatasync() performanter sein.

Vergessen Sie nicht, eio_close() nach dem Abschluss der fsync-Operation aufzurufen, um den Datei-Deskriptor freizugeben und Ressourcen-Lecks zu vermeiden.

Siehe auch

eio_fdatasync eio_open eio_write eio_close eio_event_loop eio_cancel