Signatur
Beschreibung
gearman_job_status() fragt den Gearman-Server nach dem aktuellen Ausführungsstatus eines zuvor gestarteten Hintergrund-Jobs. Als Eingabe wird das Job-Handle benötigt, das beim Einreihen des Jobs mit GearmanClient::doBackground() oder GearmanClient::doHighBackground() zurückgegeben wurde.
Die Funktion gibt ein Array mit vier Elementen zurück: ob der Job bekannt ist, ob er gerade ausgeführt wird, sowie den Fortschritt als Zähler (Numerator) und Gesamtanzahl (Denominator). Diese Informationen eignen sich besonders für Polling-Mechanismen, bei denen ein Client periodisch den Stand eines lang laufenden Prozesses abfragen möchte, ohne eine persistente Verbindung zu halten.
Die prozedurale Variante gearman_job_status() ist das funktionale Äquivalent zur Methode GearmanClient::jobStatus() der objektorientierten API. In modernen PHP-Anwendungen wird die OOP-Variante bevorzugt, jedoch ist die prozedurale Form in älteren Codebasen verbreitet.
Zu beachten ist, dass der Fortschrittswert nur dann aussagekräftig ist, wenn der Worker die Statusaktualisierungen aktiv über GearmanJob::sendStatus() an den Server übermittelt. Ohne diese Aufrufe im Worker bleiben Numerator und Denominator auf 0.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $client Pflicht | GearmanClient | Eine aktive GearmanClient-Instanz, die mit einem Gearman-Server verbunden ist. |
|
| $job_handle Pflicht | string | Das Job-Handle, das beim Einreihen des Hintergrund-Jobs zurückgegeben wurde (z. B. von GearmanClient::doBackground()). |
Rückgabewert
Gibt ein Array mit vier Elementen zurück:
- [0] (
bool):true, wenn der Job dem Server bekannt ist. - [1] (
bool):true, wenn der Job aktuell von einem Worker ausgeführt wird. - [2] (
int): Numerator des Fortschritts (z. B. bereits abgearbeitete Einheiten). - [3] (
int): Denominator des Fortschritts (z. B. Gesamtanzahl der Einheiten).
Beispiele
Hintergrund-Job einreihen und Status pollen
<?php
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);
// Hintergrund-Job einreihen
$jobHandle = $client->doBackground('long_running_task', 'payload_data');
if ($client->returnCode() !== GEARMAN_SUCCESS) {
die('Fehler beim Einreihen des Jobs.');
}
echo "Job eingereicht, Handle: " . $jobHandle . PHP_EOL;
// Periodisch den Status abfragen
do {
sleep(1);
$status = gearman_job_status($client, $jobHandle);
$known = $status[0] ? 'Ja' : 'Nein';
$running = $status[1] ? 'Ja' : 'Nein';
$numerator = $status[2];
$denominator = $status[3];
echo "Bekannt: {$known} | Läuft: {$running} | Fortschritt: {$numerator}/{$denominator}" . PHP_EOL;
} while ($status[0] || $status[1]);
echo "Job abgeschlossen." . PHP_EOL;Vergleich: prozedural vs. OOP
<?php
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);
$handle = $client->doBackground('my_function', 'some_data');
// Prozedurale Variante
$statusProc = gearman_job_status($client, $handle);
// OOP-Variante (bevorzugt in modernem PHP)
$statusOop = $client->jobStatus($handle);
// Beide liefern identische Arrays
var_dump($statusProc === $statusOop); // bool(true)
echo "Job bekannt (OOP): " . ($statusOop[0] ? 'Ja' : 'Nein') . PHP_EOL;
echo "Job läuft (prozedural): " . ($statusProc[1] ? 'Ja' : 'Nein') . PHP_EOL;// Wichtig · Fallstricke
Fortschritt nur mit Worker-Unterstützung: Numerator und Denominator bleiben 0/0, wenn der Worker nicht explizit GearmanJob::sendStatus(int $numerator, int $denominator) aufruft. Ohne diesen Aufruf ist nur der Bekannt/Läuft-Status verfügbar.
Job-Handle-Lebensdauer: Nach Abschluss eines Jobs entfernt der Gearman-Server das Handle. Kurz danach liefert gearman_job_status() [false, false, 0, 0]. Das Ende des Jobs sollte daher anhand des Übergangs von bekannt zu unbekannt erkannt werden.
Prozedurale API: Die prozedurale Gearman-Erweiterung gilt als veraltet. Neue Projekte sollten die OOP-API mit GearmanClient::jobStatus() verwenden.