eio_sync — Funktion · PHP-Referenz

Signatur

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

Beschreibung

eio_sync() führt einen asynchronen sync-Systemaufruf durch, der alle gepufferten Dateisystem-Schreiboperationen des Kernels auf die physischen Datenträger überträgt. Im Gegensatz zu fsync (das eine einzelne Datei betrifft) veranlasst sync das Betriebssystem, alle ausstehenden Schreibvorgänge in den Puffern des Kernels zu persistieren.

Die Funktion arbeitet nicht-blockierend: Der Aufruf selbst kehrt sofort zurück und gibt eine Request-Ressource zurück. Sobald der Kernel den Sync abgeschlossen hat, wird die angegebene $callback-Funktion aufgerufen. Dieses Muster ist typisch für die eio-Extension, die auf libeio basiert und asynchrone I/O für PHP ermöglicht.

Sinnvoll ist eio_sync() immer dann, wenn nach einer Serie von Schreiboperationen sichergestellt werden muss, dass alle Daten tatsächlich auf dem Speichermedium gelandet sind – etwa vor einem kontrollierten Systemherunterfahren, nach kritischen Datenbank-Bulk-Writes oder in hochverfügbaren Server-Anwendungen.

Die eio-Extension muss installiert und aktiv sein (pecl install eio). Die Ereignisschleife wird typischerweise mit eio_event_loop() gestartet, bis alle ausstehenden Requests abgearbeitet sind.

Parameter

Name	Typ	Default	Beschreibung
$pri	int	EIO_PRI_DEFAULT	Priorität des Requests. Mögliche Werte: `EIO_PRI_MIN`, `EIO_PRI_DEFAULT`, `EIO_PRI_MAX`. Bestimmt die Reihenfolge der Abarbeitung innerhalb der eio-Warteschlange.
$callback	callable	null	Eine Callback-Funktion, die nach Abschluss des Sync aufgerufen wird. Signatur: `function(mixed $data, int $result): void`. `$result` enthält `0` bei Erfolg oder `-1` bei einem Fehler.
$data	mixed	null	Beliebige benutzerdefinierte Daten, die unverändert an den `$callback` weitergereicht werden. Nützlich um Kontext (z. B. Request-IDs, Objekte) in den Callback zu transportieren.

Rückgabewert

Typ

resource|false

Beschreibung

Gibt bei Erfolg eine eio-Request-Ressource zurück, mit der der ausstehende Request z. B. per eio_cancel() abgebrochen werden kann. Bei einem Fehler wird false zurückgegeben.

Beispiele

Einfacher sync mit Callback und Ereignisschleife

<?php
// Sicherstellen, dass die eio-Extension geladen ist
if (!extension_loaded('eio')) {
    die('eio-Extension nicht verfügbar.');
}

// Callback, der nach dem Sync aufgerufen wird
$onSync = function (mixed $data, int $result): void {
    if ($result === 0) {
        echo "Sync erfolgreich: Alle Puffer wurden auf die Festplatte geschrieben.\n";
    } else {
        echo "Sync fehlgeschlagen. Fehlercode: " . eio_get_last_error($data) . "\n";
    }
};

// Asynchronen Sync starten
$request = eio_sync(EIO_PRI_DEFAULT, $onSync, null);

if ($request === false) {
    echo "eio_sync() konnte nicht gestartet werden.\n";
} else {
    // Ereignisschleife laufen lassen, bis alle Requests abgearbeitet sind
    eio_event_loop();
}

Sync erfolgreich: Alle Puffer wurden auf die Festplatte geschrieben.

Sync nach einer Serie von asynchronen Schreiboperationen

<?php
$tmpFile = tempnam(sys_get_temp_dir(), 'eio_test_');
$pending = 2; // 1x eio_write + 1x eio_sync

$checkDone = function () use (&$pending): void {
    $pending--;
    if ($pending === 0) {
        echo "Alle I/O-Operationen abgeschlossen und auf Festplatte gesichert.\n";
    }
};

// Datei öffnen und schreiben
eio_open($tmpFile, EIO_O_WRONLY | EIO_O_CREAT, 0644, EIO_PRI_DEFAULT,
    function (mixed $data, mixed $result) use ($checkDone): void {
        if ($result < 0) {
            echo "Fehler beim Öffnen der Datei.\n";
            return;
        }
        $fd = $result;
        eio_write($fd, "Wichtige Daten\n", 15, 0, EIO_PRI_DEFAULT,
            function (mixed $data, int $written) use ($fd, $checkDone): void {
                eio_close($fd);
                $checkDone();

                // Jetzt alle Puffer auf Platte schreiben
                eio_sync(EIO_PRI_DEFAULT, function (mixed $d, int $res) use ($checkDone): void {
                    $checkDone();
                });
            }
        );
    }
);

eio_event_loop();
unlink($tmpFile);

Alle I/O-Operationen abgeschlossen und auf Festplatte gesichert.

// Wichtig · Fallstricke

Performance-Hinweis: eio_sync() ist ein teurer Systemaufruf, da der Kernel alle schmutzen Puffer (Dirty Buffers) des gesamten Systems flusht. Bei häufigen Aufrufen kann dies die I/O-Performance erheblich beeinträchtigen. Für einzelne Dateien sind eio_fsync() oder eio_fdatasync() die bevorzugte Wahl.

Plattformunterstützung: sync(2) ist ein POSIX-Systemaufruf und steht unter Linux und macOS zur Verfügung. Unter Windows ist die eio-Extension nicht nutzbar.

Ereignisschleife: Ohne den Aufruf von eio_event_loop() oder eine Integration in eine externe Ereignisschleife (z. B. libuv via ReactPHP) wird der Callback nie ausgeführt. Darauf sollte stets geachtet werden.

Siehe auch

eio_fsync eio_fdatasync eio_event_loop eio_cancel eio_get_last_error