GearmanTask — Klasse · PHP-Referenz

Signatur

class GearmanTask

Beschreibung

GearmanTask ist ein Objekt, das eine einzelne, einem GearmanClient zugewiesene Aufgabe (Task) kapselt. Es wird typischerweise nicht direkt instanziiert, sondern von Methoden wie GearmanClient::addTask(), GearmanClient::addTaskBackground() oder ähnlichen zurückgegeben. Über dieses Objekt lässt sich der Lebenzyklus einer Gearman-Aufgabe verfolgen.

Innerhalb von Callback-Funktionen, die dem GearmanClient via setCompleteCallback(), setDataCallback(), setStatusCallback() oder verwandten Methoden zugewiesen wurden, erhält man ein GearmanTask-Objekt als Parameter. Damit kann man auf Rückgabewerte, Fortschrittsinformationen, eindeutige Job-Handles und Fehlerinformationen zugreifen.

Typische Anwendungsfälle sind das parallele Ausführen mehrerer Aufgaben (mittels GearmanClient::runTasks()) und die Auswertung der Ergebnisse jeder einzelnen Task im jeweiligen Callback. Die Klasse bietet Methoden zur Abfrage des Job-Handles, des Fortschritts (Numerator/Denominator), des Datenrückgabewerts sowie von Funktionsname und eindeutiger ID.

Hinweis: Die Gearman-Erweiterung muss auf dem Server installiert sein (pecl install gearman). Ein laufender gearmand-Daemon sowie mindestens ein Worker sind erforderlich, damit Tasks tatsächlich verarbeitet werden.

Beispiele

Mehrere Tasks parallel ausführen und Ergebnisse per Callback auswerten

<?php
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);

$results = [];

// Callback wird aufgerufen, wenn eine Task abgeschlossen ist
$client->setCompleteCallback(function (GearmanTask $task) use (&$results) {
    $unique = $task->unique();
    $data   = $task->data();
    $results[$unique] = $data;
    echo "Task '{$unique}' abgeschlossen. Ergebnis: {$data}" . PHP_EOL;
});

// Mehrere Tasks hinzufügen
$client->addTask('reverse', 'Hallo Welt', null, 'task-1');
$client->addTask('reverse', 'Gearman rocks', null, 'task-2');
$client->addTask('reverse', 'PHP ist toll', null, 'task-3');

// Alle Tasks ausführen (blockiert bis alle fertig sind)
$client->runTasks();

print_r($results);

Task 'task-1' abgeschlossen. Ergebnis: tleW ollaH Task 'task-2' abgeschlossen. Ergebnis: skcor namraeG Task 'task-3' abgeschlossen. Ergebnis: llot tsi PHP Array ( [task-1] => tleW ollaH [task-2] => skcor namraeG [task-3] => llot tsi PHP )

Fortschritt einer Task mit Status-Callback verfolgen

<?php
$client = new GearmanClient();
$client->addServer('127.0.0.1', 4730);

$client->setStatusCallback(function (GearmanTask $task) {
    $handle    = $task->jobHandle();
    $numerator = $task->taskNumerator();
    $denom     = $task->taskDenominator();
    echo "Job-Handle: {$handle} | Fortschritt: {$numerator}/{$denom}" . PHP_EOL;
});

$client->setCompleteCallback(function (GearmanTask $task) {
    echo "Fertig! Funktion: " . $task->functionName() . PHP_EOL;
    echo "Daten: " . $task->data() . PHP_EOL;
});

$client->setFailCallback(function (GearmanTask $task) {
    echo "Fehler bei Task: " . $task->unique() . PHP_EOL;
});

// Task mit Statusmeldungen hinzufügen (Worker muss sendStatus() aufrufen)
$client->addTask('long_running_job', json_encode(['iterations' => 10]), null, 'progress-task');
$client->runTasks();

Job-Handle: H:worker:1 | Fortschritt: 1/10 Job-Handle: H:worker:1 | Fortschritt: 5/10 Job-Handle: H:worker:1 | Fortschritt: 10/10 Fertig! Funktion: long_running_job Daten: done

// Wichtig · Fallstricke

Methoden-Übersicht: GearmanTask stellt u. a. folgende Methoden bereit:

GearmanTask::data() — Gibt die von einem Worker zurückgegebenen Daten zurück.
GearmanTask::dataSize() — Größe der zurückgegebenen Daten in Bytes.
GearmanTask::functionName() — Name der registrierten Worker-Funktion.
GearmanTask::jobHandle() — Eindeutiger Job-Handle des Gearman-Servers.
GearmanTask::returnCode() — Letzter Rückgabecode (z. B. GEARMAN_SUCCESS).
GearmanTask::taskNumerator() / GearmanTask::taskDenominator() — Fortschrittswerte, sofern der Worker GearmanJob::sendStatus() aufruft.
GearmanTask::unique() — Die benutzerdefinierte eindeutige ID der Task.

Versionierung: Die PECL-Gearman-Erweiterung hat keine strikte Versionsbindung an PHP-Releases. Stellen Sie sicher, dass die installierte Erweiterungsversion mit Ihrer PHP-Version kompatibel ist (pecl install gearman).

Fehlerbehandlung: Prüfen Sie nach runTasks() stets, ob $client->returnCode() === GEARMAN_SUCCESS gilt, und registrieren Sie einen setFailCallback(), um fehlgeschlagene Tasks nicht stillschweigend zu ignorieren.

Siehe auch

GearmanClient GearmanWorker GearmanJob GearmanException