eio_readahead — Funktion · PHP-Referenz

Signatur

eio_readahead(mixed $fd, int $offset, int $length, int $pri = EIO_PRI_DEFAULT, callable $callback = null, mixed $data = null): resource

Beschreibung

eio_readahead() gehört zur eio-Erweiterung und gibt dem Betriebssystem den Hinweis, den angegebenen Bereich einer Datei (ab offset mit der Länge length Bytes) vorab in den Seiten-Cache zu laden. Der eigentliche Lesevorgang findet im Hintergrund statt, sodass nachfolgende Lesezugriffe auf denselben Bereich ohne Warten auf I/O-Operationen bedient werden können.

Die Funktion ist besonders nützlich in Szenarien, in denen der Anwendungscode bereits weiß, welche Dateibereiche in naher Zukunft benötigt werden – beispielsweise beim sequenziellen Streaming großer Dateien oder bei der Verarbeitung von Mediadaten. Durch das Prefetching kann die wahrgenommene Latenz deutlich reduziert werden, weil die Daten beim tatsächlichen Lesezugriff bereits im RAM vorliegen.

Die Funktion ist nicht-blockierend: Sie gibt sofort eine Ressource zurück und ruft bei Abschluss des Vorgangs die angegebene callback-Funktion auf. Der Rückgabewert des Callbacks enthält das Ergebnis der Operation. Das Prefetching hat keinen Einfluss auf den Dateiinhalt selbst und verändert den Datei-Offset nicht.

Zu beachten ist, dass eio_readahead() intern den POSIX-readahead()-Systemaufruf verwendet, der nur auf Linux verfügbar ist. Auf anderen Betriebssystemen wird der Aufruf möglicherweise emuliert oder ignoriert.

Parameter

Name	Typ	Default	Beschreibung
$fd Pflicht	mixed		Datei-Deskriptor oder Stream-Ressource der zu prefetchenden Datei. Muss mit Leseberechtigung geöffnet sein.
$offset Pflicht	int		Byte-Offset innerhalb der Datei, ab dem das Prefetching beginnen soll. Muss `>= 0` sein.
$length Pflicht	int		Anzahl der Bytes, die vorab in den Seiten-Cache geladen werden sollen.
$pri	int	EIO_PRI_DEFAULT	Priorität der Anfrage. Mögliche Werte: `EIO_PRI_MIN`, `EIO_PRI_DEFAULT`, `EIO_PRI_MAX`.
$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 oder `-1` bei Fehler.
$data	mixed	null	Beliebige benutzerdefinierte Daten, die unverändert an die Callback-Funktion übergeben werden.

Rückgabewert

Typ

resource|false

Beschreibung

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

Beispiele

Dateibereich asynchron in den Cache laden

<?php
// eio-Erweiterung muss installiert und geladen sein
$filename = '/var/data/grossedatei.bin';
$fd = fopen($filename, 'rb');

if ($fd === false) {
    die('Datei konnte nicht geöffnet werden.');
}

// Ersten 1 MB der Datei vorab in den Cache laden
$req = eio_readahead(
    $fd,
    0,          // Offset: Anfang der Datei
    1024 * 1024, // Länge: 1 MB
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) use ($fd) {
        if ($result === 0) {
            echo "Prefetch erfolgreich abgeschlossen.\n";
        } else {
            echo "Fehler beim Prefetch: " . eio_get_last_error($req) . "\n";
        }
        fclose($fd);
    },
    null
);

eio_event_loop();

Prefetch erfolgreich abgeschlossen.

Gestaffeltes Prefetching mit benutzerdefinierten Daten

<?php
$filename = '/var/data/video.mp4';
$fd = fopen($filename, 'rb');
$chunkSize = 4 * 1024 * 1024; // 4 MB pro Chunk

// Zweiten Chunk (Bytes 4 MB – 8 MB) vorab laden,
// während der erste bereits verarbeitet wird
$req = eio_readahead(
    $fd,
    $chunkSize,  // Offset: 4 MB
    $chunkSize,  // Länge: 4 MB
    EIO_PRI_DEFAULT,
    function ($data, $result, $req) {
        echo "Prefetch für Chunk '{$data['label']}' abgeschlossen. Ergebnis: {$result}\n";
    },
    ['label' => 'Chunk 2']
);

eio_event_loop();
fclose($fd);

Prefetch für Chunk 'Chunk 2' abgeschlossen. Ergebnis: 0

// Wichtig · Fallstricke

Plattformabhängigkeit: Der zugrundeliegende POSIX-Systemaufruf readahead() ist nur unter Linux nativ verfügbar. Auf macOS, Windows und anderen Betriebssystemen kann die eio-Bibliothek das Verhalten emulieren, indem die Daten tatsächlich gelesen und verworfen werden – das erzeugt dennoch den gewünschten Cache-Effekt, ist jedoch weniger effizient.

Kein Einfluss auf den Datei-Offset: eio_readahead() verändert den aktuellen Datei-Offset nicht, sodass nachfolgende fread()- oder eio_read()-Aufrufe wie erwartet funktionieren.

Ressourcen-Verwaltung: Die Anfrage-Ressource sollte nicht zu früh freigegeben werden. Der Datei-Deskriptor muss bis zum Aufruf des Callbacks geöffnet bleiben, da eio intern auf den Deskriptor zugreift.

Siehe auch

eio_read eio_open eio_cancel eio_event_loop eio_get_last_error