eio_sync_file_range — Funktion · PHP-Referenz

Signatur

eio_sync_file_range(mixed $fd, int $offset, int $nbytes, int $flags, int $pri = EIO_PRI_DEFAULT, callable $callback = NULL, mixed $data = NULL): resource

Beschreibung

eio_sync_file_range() ist Teil der eio-Erweiterung und bietet eine asynchrone Schnittstelle zum Linux-Systemaufruf sync_file_range(2). Die Funktion fordert das Betriebssystem auf, einen definierten Bereich einer Datei – angegeben durch Offset und Byte-Anzahl – mit dem physischen Datenträger zu synchronisieren, ohne die gesamte Datei flushen zu müssen.

Dies ist besonders nützlich in hochperformanten I/O-Szenarien, wo nur bestimmte Segmente einer großen Datei persistiert werden müssen, z. B. beim sequenziellen Schreiben von Log-Dateien oder Datenbanken. Im Gegensatz zu eio_fsync() oder eio_fdatasync() erlaubt es eine feinere Kontrolle über den zu synchronisierenden Bereich.

Das Verhalten wird über den Parameter flags gesteuert: Es kann wahlweise nur ein Schreib-Start angefordert werden, auf den Abschluss wartend synchronisiert oder noch ausstehende Dirty Pages in die Warteschlange gestellt werden. Die Funktion ist nicht-blockierend – die eigentliche Synchronisierung erfolgt im Hintergrund, der Callback wird nach Abschluss aufgerufen.

Hinweis: Diese Funktion ist nur unter Linux verfügbar, da sync_file_range(2) ein Linux-spezifischer Systemaufruf ist. Auf anderen Plattformen ist die Funktion nicht verfügbar oder wirkt möglicherweise wie fdatasync.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Ein gültiger Datei-Deskriptor, der zuvor z. B. mit `eio_open()` geöffnet wurde.
$offset Pflicht	int		Der Byte-Offset innerhalb der Datei, ab dem die Synchronisierung beginnen soll.
$nbytes Pflicht	int		Die Anzahl der Bytes, die synchronisiert werden sollen. Der Wert `0` bedeutet, dass bis zum Ende der Datei synchronisiert wird.
$flags Pflicht	int		Bitmaske zur Steuerung des Sync-Verhaltens. Mögliche Werte sind Kombinationen aus `EIO_SYNC_FILE_RANGE_WAIT_BEFORE`, `EIO_SYNC_FILE_RANGE_WRITE` und `EIO_SYNC_FILE_RANGE_WAIT_AFTER`.
$pri	int	EIO_PRI_DEFAULT	Priorität des Requests. Mögliche Werte: `EIO_PRI_DEFAULT`, `EIO_PRI_MIN`, `EIO_PRI_MAX`.
$callback	callable	NULL	Callback-Funktion, die nach Abschluss des Vorgangs aufgerufen wird. Sie erhält die Parameter `$data`, `$result` und `$req`.
$data	mixed	NULL	Beliebige Benutzerdaten, die unverändert an den Callback übergeben werden.

Rückgabewert

Typ

resource

Beschreibung

Gibt eine eio-Request-Ressource bei Erfolg zurück, oder false im Fehlerfall.

Beispiele

Asynchrones Synchronisieren eines Dateibereichs

<?php
// eio-Event-Loop initialisieren
eio_init();

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

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

        $fd = $result;

        // Zuerst etwas in die Datei schreiben
        eio_write(
            $fd,
            str_repeat('A', 4096),
            4096,
            0,
            EIO_PRI_DEFAULT,
            function ($data, $result, $req) use ($fd) {
                // Jetzt den ersten 2048-Byte-Bereich mit dem Datenträger synchronisieren
                eio_sync_file_range(
                    $fd,
                    0,
                    2048,
                    EIO_SYNC_FILE_RANGE_WRITE | EIO_SYNC_FILE_RANGE_WAIT_AFTER,
                    EIO_PRI_DEFAULT,
                    function ($data, $result, $req) use ($fd) {
                        if ($result === 0) {
                            echo "Dateibereich erfolgreich synchronisiert." . PHP_EOL;
                        } else {
                            echo "Fehler beim Synchronisieren: " . eio_get_last_error($req) . PHP_EOL;
                        }
                        eio_close($fd);
                    }
                );
            }
        );
    }
);

eio_event_loop();
unlink($tmpfile);
?>

Dateibereich erfolgreich synchronisiert.

// Wichtig · Fallstricke

Plattformabhängigkeit: eio_sync_file_range() basiert auf dem Linux-Systemaufruf sync_file_range(2) und ist daher ausschließlich unter Linux verfügbar. Auf anderen Betriebssystemen (macOS, BSD, Windows) steht diese Funktion nicht zur Verfügung.

Fehlkonfiguration von flags: Das Setzen von EIO_SYNC_FILE_RANGE_WAIT_AFTER ohne EIO_SYNC_FILE_RANGE_WRITE kann dazu führen, dass auf Dirty Pages gewartet wird, die noch nicht zur Synchronisierung eingeplant wurden. In der Praxis empfiehlt sich die Kombination EIO_SYNC_FILE_RANGE_WRITE | EIO_SYNC_FILE_RANGE_WAIT_AFTER für ein vollständiges Flush des Bereichs.

Kein Ersatz für fsync: sync_file_range gibt keine Garantie, dass Metadaten (z. B. Dateigrößenänderungen) ebenfalls auf den Datenträger geschrieben werden. Für vollständige Datensicherheit sollte nach kritischen Schreiboperationen eio_fsync() verwendet werden.

Siehe auch

eio_fsync eio_fdatasync eio_open eio_write eio_event_loop