<?php
/*
+--------------------------------------------------------------------+
- | CiviCRM version 4.5 |
+ | CiviCRM version 4.6 |
+--------------------------------------------------------------------+
| Copyright CiviCRM LLC (c) 2004-2014 |
+--------------------------------------------------------------------+
| GNU Affero General Public License or the licensing of CiviCRM, |
| see the CiviCRM license FAQ at http://civicrm.org/licensing |
+--------------------------------------------------------------------+
-*/
+ */
/**
* The queue runner is a helper which runs all jobs in a queue.
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]);
}
* 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();
}
/**
* @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',
+ );
}
/**
$_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
}
/**
*
* 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);
/**
* 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) {
$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);
/**
* 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) {
}
/**
- * @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) {
}
/**
- *
- * @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)) {
}
/**
+ * Format a result record which describes whether the task completed.
*
- * @param $isOK
- * @param null $exception
+ * @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)
+ * @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();
}
return $this->taskCtx;
}
-}
+}
projects / civicrm-core.git / blobdiff