Queue - When UserJob.queue_id works down to zero tasks, update status and fire hook
authorTim Otten <totten@civicrm.org>
Tue, 7 Jun 2022 08:46:34 +0000 (01:46 -0700)
committerTim Otten <totten@civicrm.org>
Tue, 7 Jun 2022 09:58:09 +0000 (02:58 -0700)
commit677170bdd275721d2187d8ecd1d8734163342bf3
tree08ea7d59046c3ac48da29866f871269480e27a75
parentc4a6ea3f4397aeec5ec3705ac3dbf73e3845772c
Queue - When UserJob.queue_id works down to zero tasks, update status and fire hook

Suppose you setup a queue with several tasks and then run them all. What happens
to the queue's status?

Before
------

The status always remains `active`.

After
-----

Depends on the use-case:

* If you have an open-ended queue providing an on-going service (no `UserJob`),
  then the status remains `active`.
* If you have a fixed-purpose queue attached to a `UserJob`, then the status
  changes from `active` to `completed`, and it fires an event:
    ```
    function hook_civicrm_queueStatus(CRM_Queue_Queue $queue, string $status)
    ```

Technical Details
-----------------

* There are two main ways that items get removed from a queue (`Queue.runNext`
  API and `civicrm/queue/ajax/runNext`).  Both of these fire an internal event
  (`civi.queue.check`) to consult the status.
CRM/Core/BAO/UserJob.php
CRM/Queue/Queue.php
CRM/Queue/Runner.php
CRM/Utils/Hook.php
Civi/Api4/Action/Queue/RunItems.php
tests/phpunit/CRM/Queue/QueueTest.php
tests/phpunit/api/v4/Entity/QueueTest.php