Signatur
Beschreibung
pcntl_alarm() registriert einen einmaligen Alarm-Timer für den laufenden PHP-Prozess. Nach Ablauf der angegebenen Sekundenanzahl sendet das Betriebssystem ein SIGALRM-Signal an den Prozess. Dieses Signal kann mit pcntl_signal() abgefangen und mit einer eigenen Handler-Funktion verarbeitet werden.
Die Funktion ist besonders nützlich, um blockierende Operationen (z. B. langsame Netzwerkzugriffe, hängende Datenbankabfragen) mit einem Timeout zu versehen. Wird der Alarm ausgelöst und kein Handler registriert, beendet das Standardverhalten des Systems den Prozess.
Wird pcntl_alarm() erneut aufgerufen, bevor der vorherige Timer abgelaufen ist, wird dieser überschrieben. Der Aufruf mit $seconds = 0 bricht einen laufenden Alarm ab. Die Funktion gibt die Anzahl der Sekunden zurück, die beim vorherigen Alarm noch verbleiben hätten – oder 0, wenn kein Alarm aktiv war.
Hinweis: pcntl_alarm() ist nur unter Unix-ähnlichen Betriebssystemen verfügbar und steht unter Windows nicht zur Verfügung. Das PCNTL-Modul muss bei der Kompilierung eingebunden worden sein.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $seconds Pflicht | int | Anzahl der Sekunden bis zum Senden des SIGALRM-Signals. Bei 0 wird ein laufender Alarm abgebrochen, ohne ein neues Signal zu planen. |
Rückgabewert
0 zurückgegeben.Beispiele
Einfacher Alarm mit Signal-Handler
<?php
// Signal-Handler für SIGALRM registrieren
pcntl_signal(SIGALRM, function (int $signo) {
echo "Alarm ausgelöst! Signal: $signo" . PHP_EOL;
});
// Alarm in 3 Sekunden auslösen
$remaining = pcntl_alarm(3);
echo "Vorheriger Alarm hatte noch $remaining Sekunden." . PHP_EOL;
// Auf das Signal warten
echo "Warte auf Alarm..." . PHP_EOL;
sleep(5); // Blockierende Operation
// Signale verarbeiten (bei async_signals nicht nötig)
pcntl_signal_dispatch();
echo "Fertig." . PHP_EOL;Timeout für eine blockierende Operation
<?php
// Asynchrone Signalverarbeitung aktivieren (PHP 7.1+)
pcntl_async_signals(true);
$timedOut = false;
pcntl_signal(SIGALRM, function () use (&$timedOut) {
$timedOut = true;
echo "Timeout: Operation hat zu lange gedauert!" . PHP_EOL;
// Prozess oder Operation hier abbrechen
exit(1);
});
// Timeout von 5 Sekunden setzen
pcntl_alarm(5);
echo "Starte lange Operation..." . PHP_EOL;
// Simuliert eine lang laufende Operation
sleep(10);
// Alarm abbrechen, falls die Operation rechtzeitig fertig war
pcntl_alarm(0);
echo "Operation erfolgreich abgeschlossen." . PHP_EOL;// Wichtig · Fallstricke
Plattformabhängigkeit: pcntl_alarm() ist ausschließlich auf Unix/Linux-Systemen verfügbar. Unter Windows wird diese Funktion nicht unterstützt.
Nur ein Alarm gleichzeitig: Das Betriebssystem erlaubt pro Prozess nur einen aktiven Alarm-Timer. Ein erneuter Aufruf von pcntl_alarm() überschreibt den bestehenden Timer. Soll der vorherige Restwert nicht verloren gehen, sollte er aus dem Rückgabewert gesichert werden.
Interaktion mit sleep() und usleep(): Wenn SIGALRM eintrifft, während der Prozess in sleep() wartet, wird die Wartefunktion vorzeitig unterbrochen. Dies ist ein häufiger Fallstrick: Code nach sleep() wird früher als erwartet ausgeführt.
CLI-Kontext: Die Funktion ist primär für CLI-Skripte gedacht. Im Web-Server-Kontext (z. B. PHP-FPM, mod_php) ist ihr Einsatz unüblich und kann unerwünschte Nebeneffekte haben.