eio_fdatasync — Funktion · PHP-Referenz

Signatur

eio_fdatasync(mixed $fd, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

Beschreibung

eio_fdatasync() ist Teil der eio-Erweiterung und führt einen asynchronen fdatasync()-Systemaufruf durch. Dabei werden alle ausstehenden Schreibpuffer einer geöffneten Datei auf den Datenträger gespült – im Unterschied zu eio_fsync() jedoch ohne zwingend die vollständigen Dateimetadaten (z. B. Zugriffszeitstempel) zu aktualisieren. Das reduziert die Anzahl der nötigen Schreiboperationen und ist daher schneller als ein vollständiges fsync.

Die Funktion arbeitet nicht-blockierend: Sie gibt sofort eine Anforderungs-Ressource zurück und ruft nach Abschluss der I/O-Operation die angegebene $callback-Funktion auf. Der Callback erhält den Rückgabewert der Operation (0 bei Erfolg, -1 bei Fehler), optionale Nutzdaten sowie den Anforderungstyp.

Typische Einsatzgebiete sind datenbankähnliche Schreibszenarien, bei denen sichergestellt werden muss, dass Nutzdaten physisch auf dem Datenträger gespeichert sind, bevor eine Transaktion als abgeschlossen gilt – etwa in Logging-Systemen oder Datei-basierten Caches.

Voraussetzung für die Verwendung ist, dass die eio-PECL-Erweiterung installiert und zusammen mit einer Event-Schleife (z. B. ev oder event) eingesetzt wird.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Dateideskriptor der zu synchronisierenden Datei. Kann ein Stream-Ressource oder eine Integer-Dateideskriptor-Nummer sein, wie sie von `eio_open()` zurückgegeben wird.
$pri	int	EIO_PRI_DEFAULT	Priorität der Anforderung. Mögliche Werte: `EIO_PRI_MIN`, `EIO_PRI_DEFAULT`, `EIO_PRI_MAX`. Beeinflusst die Reihenfolge, in der Anforderungen aus der Warteschlange abgearbeitet werden.
$callback	callable	NULL	Callback-Funktion, die nach Abschluss der Operation aufgerufen wird. Signatur: `function(mixed $data, int $result, resource $req): void`. `$result` ist 0 bei Erfolg, -1 bei Fehler.
$data	mixed	NULL	Beliebige Nutzdaten, die unverändert an die Callback-Funktion weitergereicht werden. Nützlich, um Kontext (z. B. Dateinamen, Transaktions-IDs) zum Callback zu transportieren.

Rückgabewert

Typ

resource|false

Beschreibung

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

Beispiele

Datei asynchron schreiben und mit fdatasync sichern

<?php
// Voraussetzung: eio-Erweiterung ist installiert

$tmpFile = tempnam(sys_get_temp_dir(), 'eio_');

eio_open(
    $tmpFile,
    EIO_O_WRONLY | EIO_O_CREAT | EIO_O_TRUNC,
    0600,
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) use ($tmpFile) {
        if ($result < 0) {
            echo 'Fehler beim Öffnen: ' . eio_get_last_error($req) . PHP_EOL;
            return;
        }
        $fd = $result;

        // Schreiboperation starten
        eio_write(
            $fd,
            'Wichtige Nutzdaten',
            18,
            0,
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd) {
                // Nach dem Schreiben: fdatasync aufrufen
                eio_fdatasync(
                    $fd,
                    EIO_PRI_DEFAULT,
                    function ($data, $result, $req) use ($fd) {
                        if ($result === 0) {
                            echo 'fdatasync erfolgreich – Daten sind auf dem Datenträger.' . PHP_EOL;
                        } else {
                            echo 'fdatasync fehlgeschlagen: ' . eio_get_last_error($req) . PHP_EOL;
                        }
                        eio_close($fd);
                    },
                    'fdatasync-Kontext'
                );
            }
        );
    }
);

eio_event_loop();

fdatasync erfolgreich – Daten sind auf dem Datenträger.

Unterschied zwischen eio_fdatasync und eio_fsync demonstrieren

<?php
// eio_fdatasync(): schreibt Dateiinhalte, aber keine vollständigen Metadaten
// eio_fsync():     schreibt Dateiinhalte UND alle Metadaten

$file = tempnam(sys_get_temp_dir(), 'sync_test_');

eio_open(
    $file,
    EIO_O_RDWR | EIO_O_CREAT,
    0644,
    EIO_PRI_DEFAULT,
    function ($data, $fd, $req) {
        eio_write($fd, 'Testdaten', 9, 0, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($fd) {
            // fdatasync – effizienter, wenn Metadaten nicht kritisch sind
            eio_fdatasync($fd, EIO_PRI_DEFAULT, function ($data, $result, $req) use ($fd) {
                echo ($result === 0)
                    ? 'Nur Dateidaten synchronisiert (kein vollständiges fsync).' . PHP_EOL
                    : 'Fehler bei fdatasync.' . PHP_EOL;
                eio_close($fd);
            });
        });
    }
);

eio_event_loop();

Nur Dateidaten synchronisiert (kein vollständiges fsync).

// Wichtig · Fallstricke

Plattformabhängigkeit: fdatasync() ist ein POSIX-Systemaufruf und steht unter Windows nicht zur Verfügung. Auf Windows-Systemen fällt eio intern auf fsync() zurück oder liefert einen Fehler.

Kein Ersatz für Transaktionen: eio_fdatasync() garantiert lediglich, dass die Daten zum Zeitpunkt des Callbacks physisch auf dem Datenträger liegen. Es stellt keine atomaren Schreiboperationen sicher. Für transaktionssichere Schreibvorgänge sollte ein temporäres Rename-Muster verwendet werden.

Kombination mit Event-Schleife: Die eio-Erweiterung muss zusammen mit einer kompatiblen Event-Schleife betrieben werden (z. B. über eio_event_loop() oder Integration in ev/libevent), da die Callbacks andernfalls nicht ausgeführt werden.

Siehe auch

eio_fsync eio_open eio_write eio_close eio_cancel eio_event_loop