gearman_job_handle — Funktion · PHP-Referenz

Signatur

gearman_job_handle(GearmanJob $job): string

Beschreibung

gearman_job_handle() gibt das Job-Handle zurück, das vom Gearman-Job-Server einem bestimmten Job zugewiesen wurde. Dieses Handle ist ein eindeutiger Bezeichner, der zur Identifikation des Jobs innerhalb des Gearman-Systems dient.

Das Job-Handle wird typischerweise benötigt, wenn ein Worker den Fortschritt oder Status eines laufenden Jobs übermitteln möchte, oder wenn der Client den Status eines asynchron gestarteten Hintergrund-Jobs abfragen will. Das Handle bleibt für die gesamte Lebensdauer des Jobs gültig.

Die Funktion ist die prozedurale Alternative zur objektorientierten Methode GearmanJob::handle(). In modernem PHP-Code wird die objektorientierte API bevorzugt, da sie eine sauberere Kapselung bietet.

Typischerweise wird gearman_job_handle() innerhalb der Worker-Callback-Funktion aufgerufen, um das Handle für Status-Updates oder Logging zu verwenden.

Parameter

Name	Typ	Default	Beschreibung
$job Pflicht	GearmanJob		Das `GearmanJob`-Objekt, dessen Handle abgerufen werden soll. Dieses Objekt wird dem Worker-Callback automatisch vom Gearman-Framework übergeben.

Rückgabewert

Typ

string

Beschreibung

Gibt das eindeutige Job-Handle als Zeichenkette zurück, das vom Gearman-Job-Server für diesen Job vergeben wurde. Das Handle hat typischerweise die Form H:hostname:nummer.

Beispiele

Job-Handle im Worker ausgeben und für Status-Updates nutzen

<?php
// Worker-Skript
$worker = new GearmanWorker();
$worker->addServer('127.0.0.1', 4730);

$worker->addFunction('meine_aufgabe', function(GearmanJob $job) {
    // Job-Handle abrufen (prozedurale Variante)
    $handle = gearman_job_handle($job);
    echo "Verarbeite Job mit Handle: " . $handle . PHP_EOL;

    // Fortschritt melden
    $job->sendStatus(50, 100);

    // Arbeit simulieren
    sleep(1);

    $job->sendStatus(100, 100);
    return "Ergebnis für " . $handle;
});

while ($worker->work()) {
    if ($worker->returnCode() != GEARMAN_SUCCESS) {
        echo "Fehler: " . $worker->error() . PHP_EOL;
        break;
    }
}

Verarbeite Job mit Handle: H:meinserver:1

Job-Handle im Client und Worker zum Abgleich verwenden

<?php
// Client-Skript: Job im Hintergrund starten und Handle speichern
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);

$hintergrundHandle = $client->doBackground('meine_aufgabe', 'Nutzdaten');
echo "Gestarteter Hintergrund-Job Handle: " . $hintergrundHandle . PHP_EOL;

// Status des Hintergrund-Jobs prüfen
sleep(1);
$client->jobStatus($hintergrundHandle, $known, $running, $numerator, $denominator);
echo "Job bekannt: " . ($known ? 'Ja' : 'Nein') . PHP_EOL;
echo "Job läuft: " . ($running ? 'Ja' : 'Nein') . PHP_EOL;
echo "Fortschritt: " . $numerator . "/" . $denominator . PHP_EOL;

// ---
// Worker-Skript (Gegenstück): Handle per gearman_job_handle() abrufen
$worker = new GearmanWorker();
$worker->addServer('127.0.0.1', 4730);

$worker->addFunction('meine_aufgabe', function(GearmanJob $job) {
    $handle = gearman_job_handle($job);
    // Handle loggen oder in DB speichern
    file_put_contents('/tmp/gearman_handles.log', $handle . PHP_EOL, FILE_APPEND);
    $job->sendStatus(1, 1);
    return strtoupper($job->workload());
});

$worker->work();

Gestarteter Hintergrund-Job Handle: H:meinserver:2 Job bekannt: Ja Job läuft: Ja Fortschritt: 0/0

// Wichtig · Fallstricke

Prozedurale vs. OOP-API: gearman_job_handle($job) ist äquivalent zu $job->handle(). In neuerem Code wird die OOP-Variante bevorzugt, da sie lesbarer und konsistenter mit dem Rest der Gearman-PHP-Erweiterung ist.

PECL-Erweiterung erforderlich: Die Funktion gehört zur gearman-PECL-Erweiterung und ist nicht Teil der PHP-Standardinstallation. Sie muss separat installiert werden (pecl install gearman). Außerdem muss ein laufender Gearman-Job-Server (gearmand) vorhanden sein.

Handle-Format: Das zurückgegebene Handle hat das Format H:hostname:sequenznummer. Die Sequenznummer wird vom Job-Server monoton hochgezählt und ist pro Server-Instanz eindeutig, aber nicht über Server-Neustarts hinweg persistent.

Siehe auch

GearmanJob::handle GearmanJob::workload GearmanJob::sendStatus GearmanClient::jobStatus GearmanClient::doBackground