X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;f=CRM%2FQueue%2FRunner.php;h=3c88e2fef031fcd60fbe40516ed7e8c28ff4557e;hb=4523a2f5418b2873da2300f4c0a044bfc6998665;hp=ff1188cd25c212649146065ae4a0ad6dbbcc967c;hpb=e8e8612badd1477f70d1b73418438376a8e985b9;p=civicrm-core.git diff --git a/CRM/Queue/Runner.php b/CRM/Queue/Runner.php index ff1188cd25..3c88e2fef0 100644 --- a/CRM/Queue/Runner.php +++ b/CRM/Queue/Runner.php @@ -35,50 +35,52 @@ class CRM_Queue_Runner { /** - * The failed task should be discarded, and queue processing should continue + * The failed task should be discarded, and queue processing should continue. */ - CONST ERROR_CONTINUE = 1; + const ERROR_CONTINUE = 1; /** - * The failed task should be kept in the queue, and queue processing should abort + * The failed task should be kept in the queue, and queue processing should + * abort. */ - CONST ERROR_ABORT = 2; + const ERROR_ABORT = 2; /** * @var string */ - var $title; + public $title; /** * @var CRM_Queue_Queue */ - var $queue; - var $errorMode; - var $isMinimal; - var $onEnd; - var $onEndUrl; - var $pathPrefix; + public $queue; + public $errorMode; + public $isMinimal; + public $onEnd; + public $onEndUrl; + public $pathPrefix; // queue-runner id; used for persistence - var $qrid; + public $qrid; /** * @var array whether to display buttons, eg ('retry' => TRUE, 'skip' => FALSE) */ - var $buttons; + public $buttons; /** * @var CRM_Queue_TaskContext */ - var $taskCtx; + public $taskCtx; /** - * Locate a previously-created instance of the queue-runner + * Locate a previously-created instance of the queue-runner. * - * @param $qrid string, the queue-runner ID + * @param string $qrid + * The queue-runner ID. * - * @return CRM_Queue_Runner or NULL + * @return CRM_Queue_Runner|NULL */ - static function instance($qrid) { + public static function instance($qrid) { if (!empty($_SESSION['queueRunners'][$qrid])) { return unserialize($_SESSION['queueRunners'][$qrid]); } @@ -92,22 +94,25 @@ class CRM_Queue_Runner { * FIXME: parameter validation * FIXME: document signature of onEnd callback * - * @param $runnerSpec array with keys: + * @param array $runnerSpec + * Array with keys: * - queue: CRM_Queue_Queue - * - errorMode: int, ERROR_CONTINUE or ERROR_ABORT - * - onEnd: mixed, a callback to update the UI after running; should be both callable and serializable - * - onEndUrl: string, the URL to which one redirects - * - pathPrefix: string, prepended to URLs for the web-runner; default: 'civicrm/queue' + * - errorMode: int, ERROR_CONTINUE or ERROR_ABORT. + * - onEnd: mixed, a callback to update the UI after running; should be + * both callable and serializable. + * - onEndUrl: string, the URL to which one redirects. + * - pathPrefix: string, prepended to URLs for the web-runner; + * default: 'civicrm/queue'. */ public function __construct($runnerSpec) { - $this->title = CRM_Utils_Array::value('title', $runnerSpec, ts('Queue Runner')); - $this->queue = $runnerSpec['queue']; - $this->errorMode = CRM_Utils_Array::value('errorMode', $runnerSpec, self::ERROR_ABORT); - $this->isMinimal = CRM_Utils_Array::value('isMinimal', $runnerSpec, FALSE); - $this->onEnd = CRM_Utils_Array::value('onEnd', $runnerSpec, NULL); - $this->onEndUrl = CRM_Utils_Array::value('onEndUrl', $runnerSpec, NULL); + $this->title = CRM_Utils_Array::value('title', $runnerSpec, ts('Queue Runner')); + $this->queue = $runnerSpec['queue']; + $this->errorMode = CRM_Utils_Array::value('errorMode', $runnerSpec, self::ERROR_ABORT); + $this->isMinimal = CRM_Utils_Array::value('isMinimal', $runnerSpec, FALSE); + $this->onEnd = CRM_Utils_Array::value('onEnd', $runnerSpec, NULL); + $this->onEndUrl = CRM_Utils_Array::value('onEndUrl', $runnerSpec, NULL); $this->pathPrefix = CRM_Utils_Array::value('pathPrefix', $runnerSpec, 'civicrm/queue'); - $this->buttons = CRM_Utils_Array::value('buttons', $runnerSpec, array('retry' => TRUE,'skip' => TRUE)); + $this->buttons = CRM_Utils_Array::value('buttons', $runnerSpec, array('retry' => TRUE, 'skip' => TRUE)); // perhaps this value should be randomized? $this->qrid = $this->queue->getName(); } @@ -115,9 +120,19 @@ class CRM_Queue_Runner { /** * @return array */ - function __sleep() { + public function __sleep() { // exclude taskCtx - return array('title', 'queue', 'errorMode', 'isMinimal', 'onEnd', 'onEndUrl', 'pathPrefix', 'qrid', 'buttons'); + return array( + 'title', + 'queue', + 'errorMode', + 'isMinimal', + 'onEnd', + 'onEndUrl', + 'pathPrefix', + 'qrid', + 'buttons', + ); } /** @@ -127,7 +142,7 @@ class CRM_Queue_Runner { $_SESSION['queueRunners'][$this->qrid] = serialize($this); $url = CRM_Utils_System::url($this->pathPrefix . '/runner', 'reset=1&qrid=' . urlencode($this->qrid)); CRM_Utils_System::redirect($url); - // TODO: evaluate items incrementally via AJAX polling, cleanup session, call + // TODO: evaluate items incrementally via AJAX polling, cleanup session } /** @@ -136,7 +151,9 @@ class CRM_Queue_Runner { * * If the runner has an onEndUrl, then this function will not return * - * @return mixed, TRUE if all tasks complete normally; otherwise, an array describing the failed task + * @return mixed + * TRUE if all tasks complete normally; otherwise, an array describing the + * failed task */ public function runAll() { $taskResult = $this->formatTaskResult(TRUE); @@ -167,11 +184,18 @@ class CRM_Queue_Runner { /** * Take the next item from the queue and attempt to run it. * - * Individual tasks may also throw exceptions -- caller should watch for exceptions + * Individual tasks may also throw exceptions -- caller should watch for + * exceptions. * - * @param $useSteal bool, whether to steal active locks + * @param bool $useSteal + * Whether to steal active locks. * - * @return array(is_error => bool, is_continue => bool, numberOfItems => int, 'last_task_title' => $, 'exception' => $) + * @return array + * - is_error => bool, + * - is_continue => bool, + * - numberOfItems => int, + * - 'last_task_title' => $, + * - 'exception' => $ */ public function runNext($useSteal = FALSE) { if ($useSteal) { @@ -189,12 +213,11 @@ class CRM_Queue_Runner { $isOK = $item->data->run($this->getTaskContext()); if (!$isOK) { $exception = new Exception('Task returned false'); - } - } - catch(Exception$e) { + } + } catch (Exception$e) { $isOK = FALSE; $exception = $e; - } + } if ($isOK) { $this->queue->deleteItem($item); @@ -213,11 +236,16 @@ class CRM_Queue_Runner { /** * Take the next item from the queue and attempt to run it. * - * Individual tasks may also throw exceptions -- caller should watch for exceptions + * Individual tasks may also throw exceptions -- caller should watch for + * exceptions. * - * @param $useSteal bool, whether to steal active locks + * @param bool $useSteal + * Whether to steal active locks. * - * @return array(is_error => bool, is_continue => bool, numberOfItems => int) + * @return array + * - is_error => bool, + * - is_continue => bool, + * - numberOfItems => int) */ public function skipNext($useSteal = FALSE) { if ($useSteal) { @@ -238,7 +266,10 @@ class CRM_Queue_Runner { } /** - * @param $item + * Release an item in keeping with the error mode. + * + * @param object $item + * The item previously produced by Queue::claimItem. */ protected function releaseErrorItem($item) { switch ($this->errorMode) { @@ -251,7 +282,11 @@ class CRM_Queue_Runner { } /** - * @return array(is_error => bool, is_continue => bool, numberOfItems => int, redirect_url => string) + * @return array + * - is_error => bool, + * - is_continue => bool, + * - numberOfItems => int, + * - redirect_url => string */ public function handleEnd() { if (is_callable($this->onEnd)) { @@ -274,12 +309,17 @@ class CRM_Queue_Runner { } /** - * @param $isOK - * @param null $exception + * Format a result record which describes whether the task completed. * - * @return array(is_error => bool, is_continue => bool, numberOfItems => int) + * @param bool $isOK + * TRUE if the task completed successfully. + * @param Exception|NULL $exception + * If applicable, an unhandled exception that arose during execution. + * + * @return array + * (is_error => bool, is_continue => bool, numberOfItems => int) */ - function formatTaskResult($isOK, $exception = NULL) { + public function formatTaskResult($isOK, $exception = NULL) { $numberOfItems = $this->queue->numberOfItems(); $result = array(); @@ -320,4 +360,3 @@ class CRM_Queue_Runner { return $this->taskCtx; } } -