Documentation

CRM_Queue_Runner
in package

`CRM_Queue_Runner` runs a list tasks from a queue. It originally supported the database-upgrade queue. Consequently, this runner is optimal for queues which are:

  • Short lived and discrete. You have a fixed list of tasks that will be run to completion.
  • Strictly linear. Tasks must run 1-by-1. Often, one task depends on the success of a previous task.
  • Slightly dangerous. An error, omission, or mistake indicates that the database is in an inconsistent state. Errors call for skilled human intervention.

This runner supports a few modes of operation, eg

  • runAllViaWeb(): Use a web-browser and a series of AJAX requests to perform all steps. If there is an error, prompt the sysadmin/user to decide how to handle it.
  • runAll(): Run all tasks, 1-by-1, back-to-back. If there is an error, give up. This is used by some CLI upgrades.

This runner is not appropriate for all queues or workloads, so you might choose or create a different runner. For example, CRM_Queue_TaskRunner is geared toward background task lists.

Tags
see
CRM_Queue_TaskRunner

Table of Contents

Constants

ERROR_ABORT  = 2
The failed task should be kept in the queue, and queue processing should abort.
ERROR_CONTINUE  = 1
The failed task should be discarded, and queue processing should continue.

Properties

$buttons  : array<string|int, mixed>
$errorMode  : mixed
$isMinimal  : mixed
$lastTaskTitle  : string
$onEnd  : mixed
$onEndUrl  : mixed
$pathPrefix  : mixed
$qrid  : int
queue-runner id; used for persistence
$queue  : CRM_Queue_Queue
$taskCtx  : CRM_Queue_TaskContext
$title  : string

Methods

__construct()  : mixed
FIXME: parameter validation FIXME: document signature of onEnd callback
__sleep()  : array<string|int, mixed>
formatTaskResult()  : array<string|int, mixed>
Format a result record which describes whether the task completed.
handleEnd()  : array<string|int, mixed>
instance()  : CRM_Queue_Runner|null
Locate a previously-created instance of the queue-runner.
runAll()  : array<string|int, mixed>|true
Immediately run all tasks in a queue (until either reaching the end of the queue or encountering an error)
runAllInteractive()  : void
[EXPERIMENTAL] Run all tasks interactively. Redirect to a screen which presents the progress.
runAllViaWeb()  : mixed
Redirect to the web-based queue-runner and evaluate all tasks in a queue.
runNext()  : array<string|int, mixed>
Take the next item from the queue and attempt to run it.
skipNext()  : array<string|int, mixed>
Take the next item from the queue and attempt to run it.
assertRequirementsBackground()  : void
Assert that we meet the requirements for running tasks in background.
assertRequirementsWeb()  : void
Assert that we meet the requirements for running tasks via AJAX.
disableBackgroundExecution()  : void
Ensure that background workers will not try to run this queue.
enableBackgroundExecution()  : void
Ensure that background workers will not try to run this queue.
findUserJob()  : array<string|int, mixed>|null
Find the `UserJob` that corresponds to this queue (if any).
getTaskContext()  : CRM_Queue_TaskContext
pickErrorMode()  : int
If the runner doesn't its own error-policy, then try to inherit the policy from the queue configuration.
releaseErrorItem()  : mixed
Release an item in keeping with the error mode.
runAllViaBackground()  : mixed

Constants

ERROR_ABORT

The failed task should be kept in the queue, and queue processing should abort.

public mixed ERROR_ABORT = 2

ERROR_CONTINUE

The failed task should be discarded, and queue processing should continue.

public mixed ERROR_CONTINUE = 1

Properties

$buttons

public array<string|int, mixed> $buttons

Whether to display buttons, eg ('retry' => TRUE, 'skip' => FALSE)

$errorMode

public mixed $errorMode

$isMinimal

public mixed $isMinimal

$lastTaskTitle

public string $lastTaskTitle

$onEndUrl

public mixed $onEndUrl

$pathPrefix

public mixed $pathPrefix

$qrid

queue-runner id; used for persistence

public int $qrid

Methods

__construct()

FIXME: parameter validation FIXME: document signature of onEnd callback

public __construct(array<string|int, mixed> $runnerSpec) : mixed
Parameters
$runnerSpec : array<string|int, mixed>

Array with keys:

  • queue: CRM_Queue_Queue
  • errorMode: int, ERROR_CONTINUE or ERROR_ABORT. If omitted, it inherits from $queue->spec['error'] or falls back to 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'.

__sleep()

public __sleep() : array<string|int, mixed>
Return values
array<string|int, mixed>

formatTaskResult()

Format a result record which describes whether the task completed.

public formatTaskResult(bool $isOK[, Exception|null $exception = NULL ]) : array<string|int, mixed>
Parameters
$isOK : bool

TRUE if the task completed successfully.

$exception : Exception|null = NULL

If applicable, an unhandled exception that arose during execution.

Return values
array<string|int, mixed> —

(is_error => bool, is_continue => bool, numberOfItems => int)

handleEnd()

public handleEnd() : array<string|int, mixed>
Return values
array<string|int, mixed> —
  • is_error => bool,
  • is_continue => bool,
  • numberOfItems => int,
  • redirect_url => string

instance()

Locate a previously-created instance of the queue-runner.

public static instance(string $qrid) : CRM_Queue_Runner|null
Parameters
$qrid : string

The queue-runner ID.

Return values
CRM_Queue_Runner|null

runAll()

Immediately run all tasks in a queue (until either reaching the end of the queue or encountering an error)

public runAll() : array<string|int, mixed>|true

If the runner has an onEndUrl, then this function will not return

Return values
array<string|int, mixed>|true —

TRUE if all tasks complete normally; otherwise, an array describing the failed task

runAllInteractive()

[EXPERIMENTAL] Run all tasks interactively. Redirect to a screen which presents the progress.

public runAllInteractive() : void

The exact mechanism and pageflow may be determined by the system configuration -- environments which support multiprocessing (background queue-workers) can use those; otherwise, they can use the traditional AJAX runner.

To ensure portability, requesters must satisfy the requirements of both/all execution mechanisms.

Tags
throws
CRM_Core_Exception

runAllViaWeb()

Redirect to the web-based queue-runner and evaluate all tasks in a queue.

public runAllViaWeb() : mixed

runNext()

Take the next item from the queue and attempt to run it.

public runNext([bool $useSteal = FALSE ]) : array<string|int, mixed>

Individual tasks may also throw exceptions -- caller should watch for exceptions.

Parameters
$useSteal : bool = FALSE

Whether to steal active locks.

Return values
array<string|int, mixed> —
  • is_error => bool,
  • is_continue => bool,
  • numberOfItems => int,
  • 'last_task_title' => $,
  • 'exception' => $

skipNext()

Take the next item from the queue and attempt to run it.

public skipNext([bool $useSteal = FALSE ]) : array<string|int, mixed>

Individual tasks may also throw exceptions -- caller should watch for exceptions.

Parameters
$useSteal : bool = FALSE

Whether to steal active locks.

Return values
array<string|int, mixed> —
  • is_error => bool,
  • is_continue => bool,
  • numberOfItems => int)

assertRequirementsBackground()

Assert that we meet the requirements for running tasks in background.

protected assertRequirementsBackground() : void
Tags
throws
CRM_Core_Exception

assertRequirementsWeb()

Assert that we meet the requirements for running tasks via AJAX.

protected assertRequirementsWeb() : void
Tags
throws
CRM_Core_Exception

disableBackgroundExecution()

Ensure that background workers will not try to run this queue.

protected disableBackgroundExecution() : void

enableBackgroundExecution()

Ensure that background workers will not try to run this queue.

protected enableBackgroundExecution() : void

findUserJob()

Find the `UserJob` that corresponds to this queue (if any).

protected findUserJob() : array<string|int, mixed>|null
Tags
throws
CRM_Core_Exception
Return values
array<string|int, mixed>|null —

The record, per APIv4. This may return NULL. UserJobs are required for runAllInteractively() and runAllViaBackground(), but (for backward compatibility) they are not required for runAllViaWeb().

pickErrorMode()

If the runner doesn't its own error-policy, then try to inherit the policy from the queue configuration.

protected pickErrorMode(CRM_Queue_Queue $queue) : int
Parameters
$queue : CRM_Queue_Queue
Return values
int

releaseErrorItem()

Release an item in keeping with the error mode.

protected releaseErrorItem(object $item) : mixed
Parameters
$item : object

The item previously produced by Queue::claimItem.

runAllViaBackground()

protected runAllViaBackground() : mixed 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results