time_nanosleep — Funktion · PHP-Referenz

Signatur

time_nanosleep(int $seconds, int $nanoseconds): array|bool

Beschreibung

time_nanosleep() hält die Ausführung des aktuellen PHP-Prozesses für die angegebene Dauer an. Im Gegensatz zu sleep() (nur Sekunden) oder usleep() (nur Mikrosekunden) erlaubt diese Funktion eine sehr präzise Steuerung der Wartezeit auf Nanosekunden-Ebene.

Wird der Schlaf durch ein Signal unterbrochen, gibt die Funktion kein true zurück, sondern ein assoziatives Array mit den Schlüsseln seconds und nanoseconds, das die verbleibende Schlafzeit enthält. Dadurch kann der Schlaf bei Bedarf fortgesetzt werden.

Die Funktion eignet sich besonders für Situationen, in denen sehr kurze, präzise Pausen benötigt werden – z. B. beim Polling auf Hardware-Ebene, bei der Ratenbegrenzung von API-Anfragen oder bei zeitkritischen Skripten, die fein granulare Wartezeiten benötigen.

Zu beachten ist, dass die tatsächliche Schlafgenauigkeit vom Betriebssystem und der Hardware abhängt. Auf vielen Systemen liegt die minimale effektive Auflösung im Bereich von einigen hundert Nanosekunden bis Mikrosekunden.

Parameter

Name	Typ	Default	Beschreibung
$seconds Pflicht	int		Die Anzahl der Sekunden, die gewartet werden soll. Muss nicht negativ sein.
$nanoseconds Pflicht	int		Die Anzahl der Nanosekunden, die zusätzlich gewartet werden soll. Muss ein Wert zwischen `0` und `999999999` sein.

Rückgabewert

Typ

array|bool

Beschreibung

Gibt true zurück, wenn der Schlaf vollständig abgelaufen ist. Gibt false zurück, wenn ungültige Parameter übergeben wurden. Wurde der Schlaf durch ein Signal unterbrochen, wird ein assoziatives Array mit den Schlüsseln seconds und nanoseconds zurückgegeben, das die noch verbleibende Schlafzeit angibt.

Beispiele

Einfache Pause von 1,5 Sekunden

<?php
// Skript für 1 Sekunde und 500 Millionen Nanosekunden (= 0,5 s) anhalten
$result = time_nanosleep(1, 500000000);

if ($result === true) {
    echo "Schlaf vollständig abgeschlossen.\n";
} elseif (is_array($result)) {
    echo "Schlaf wurde unterbrochen. Verbleibend: " 
        . $result['seconds'] . " Sekunden und " 
        . $result['nanoseconds'] . " Nanosekunden.\n";
} else {
    echo "Ungültige Parameter übergeben.\n";
}

Schlaf vollständig abgeschlossen.

Wiederholter Schlaf nach Signalunterbrechung

<?php
// Schlaf mit automatischem Neustart bei Unterbrechung durch ein Signal
$seconds = 2;
$nanoseconds = 0;

while (true) {
    $result = time_nanosleep($seconds, $nanoseconds);

    if ($result === true) {
        // Schlaf vollständig abgeschlossen
        break;
    } elseif (is_array($result)) {
        // Unterbrochen – verbleibende Zeit weiterschlafen
        $seconds     = $result['seconds'];
        $nanoseconds = $result['nanoseconds'];
        echo "Unterbrochen, schlafe weiter...\n";
    } else {
        echo "Fehler: Ungültige Parameter.\n";
        break;
    }
}

echo "Gesamter Schlaf abgeschlossen.\n";

Gesamter Schlaf abgeschlossen.

Kurze Pause zwischen API-Anfragen

<?php
// Rate-Limiting: 100 Anfragen pro Sekunde → 10 ms Pause zwischen Anfragen
$urls = [
    'https://api.example.com/item/1',
    'https://api.example.com/item/2',
    'https://api.example.com/item/3',
];

foreach ($urls as $url) {
    // Anfrage simulieren
    echo "Abruf: $url\n";

    // 10 Millisekunden = 10.000.000 Nanosekunden warten
    time_nanosleep(0, 10000000);
}

echo "Alle Anfragen abgeschlossen.\n";

Abruf: https://api.example.com/item/1 Abruf: https://api.example.com/item/2 Abruf: https://api.example.com/item/3 Alle Anfragen abgeschlossen.

// Wichtig · Fallstricke

Plattformabhängigkeit: Die tatsächliche Auflösung der Schlafzeit hängt vom Betriebssystem ab. Unter Linux ist eine Nanosekunden-Genauigkeit theoretisch möglich, in der Praxis liegt die Auflösung jedoch oft bei einigen hundert Nanosekunden oder mehr, abhängig vom Scheduler und der Hardware.

Windows: Unter Windows wird time_nanosleep() möglicherweise intern auf Millisekunden gerundet, da das Windows-Betriebssystem keine native Nanosekunden-Auflösung bietet.

Ungültige Parameter: Wird für nanoseconds ein Wert außerhalb des Bereichs 0–999999999 oder ein negativer Wert für seconds übergeben, gibt die Funktion false zurück und erzeugt eine Warnung.

Siehe auch

sleep usleep time_sleep_until microtime