Queueing: Reference¶

Civi::queue()¶

The method Civi::queue() accepts an optional specification describing the queue:

Civi::queue(string $name, array $params): CRM_Queue_Queue

The $params accepts the following keys:

Option	Default	Description	Layer (Version)
`agent`	`null`	Specifies who is responsible for polling the queue. Use `browser` or `server`.	Agent (5.68+)
`batch_limit`	`1`	Maximum number of items that an agent may claim.	Driver
`error`	`null`	If an item in the queue encounters an error and exhausts all retries, then what should be the final disposition? `abort`: Abort execution of the queue. Leave the failed item in place. `delete`: Delete the failed item. Continue execution of other items. Note: For more control over error-handling, see hook_queueTaskError.	Handler (5.47+)
`is_persistent`	`TRUE`	If true, then this queue is stored and loaded from the `civicrm_queue` table.	Management (5.47+)
`lease_time`	`3600`	How long does an agent have to complete a task. (If the agent does not report back in the time limit, then assume it has crashed.)	Driver
`payload`	`null`	Specifies the kind of content in the queue. This is typically task or a custom string.	Handler (5.68)
`reset`	`FALSE`	If true, then this queue will be destroyed and re-created. All pending tasks will be lost.	Management (4.2+)
`retry_interval`		How many seconds between attempts	Driver
`retry_limit`	`0`	How many times to attempt to run an item before giving up. `0` disables retries.	Handler
`runner`	`null`	(Deprecated) Specifies whether and how to automatically run items. Setting `runner=>foo` is equivalent to setting both `agent=>server`+`payload=>foo`.	Agent-Handler (5.47-5.68)
`type`	`null`	Specifies the driver class that is responsible for reading and writing queue-items. Options are: Sql: This is a sequential queue stored in MySQL SqlParallel: This is a concurrent queue stored in MySQL Memory: This is a sequential queue stored in PHP memory. Intended for testing.	Driver (4.2+)

Under-the-hood, these options are interpreted by different layers of the queueing framework:

Driver options describe how to enqueue/dequeue items. These are enforced by CRM_Queue_Queue_*.
Management options describe how to lookup the queue. These are enforced by CRM_Queue_Service.
Agent options describe the system which polls the queue. These are enforced externally (by the agent).
Handler options describe what to do when evaluating items. These are enforced by Queue::runItems() and its various events/listeners.

Defaults: Driver options, agent, handler options are defaults. They are stored in the registration record (civicrm_queue). Once registered, they will not change unless someone specifically updates the database.

Handler Variations: In general, any handler that participates in APIv4's Queue.runItems should respect these options, but this is discretionary. Older/lower-level runners do not respect them.

CRM_Queue_Task¶

new CRM_Queue_Task($callback, $arguments = [], $title = '')

The constructor accepts the following:

Option	Default	Description
`$callback`		PHP callback. This should be a PHP global-function or a static-method. Caution: Inline functions may struggle with serialization. Some invokable objects may be serializable, but they also require extra attention when deploying code updates.
`$arguments`	`[]`	A list of arguments to pass to the callback.
`$title`	`''`	A translated label that can be displayed to user/admin who is monitoring queue progress.

Additionally, you may override some properties after instantiating the object:

Property	Default	Description
`$runAs`	`NULL`	This is either `NULL`, or it's an array specifying `contactId` and `domainId`.

Caution: runAs requires agent support. In all cases, the value of runAs will be validated before executing. However, at time of writing, only coworker has full support for executing multi-user queues.