Queue API - Expose option for delayed tasks ($options['release_time'])

[totten]

Overview

CRM_Queue_Queue_*::createItem() allows you to create new tasks for separate/parallel execution. This patch adds an option for marking new tasks as delayed (ie they will execute at some specific time in the future).

This is an off-shoot from discussion on https://lab.civicrm.org/documentation/docs/dev/-/merge_requests/992 (@eileenmcnaughton @jaapjansma @ErikHommel).

Before

• When creating a task with CRM_Queue_Queue_*::createItem(), you cannot request delayed execution explicitly.
• However, the underlying system is amenable. (Delays are already used for locking tasks and for retrying failed tasks.)
• Some extensions already use the SQL-backed queue for delayed tasks, and there's a public recipe for doing this. But it requires one to directly manipulate the queue via SQL/DAO.

After

All core queue types (Sql, SqlParallel, Memory) all you to create a delayed task:

Civi::queue('todos')->createItem(
  new CRM_Queue_Task($callback, $args),
  ['release_time' => strtotime('+3 hours')]
);

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[totten]

Fun fact (and pre-existing issue): civicrm_queue_item.release_time uses DATETIME. This is ambiguous - there is no clear definition of the storage-time-zone.

Of course, AFAIK no one has been complaining about that. I suppose a lot of queue-stuff is done by background workers which (for a given deployment) will have consistent/mutually-agreeable TZ settings. (Or maybe it's just hard to notice - how many people will recognize when the lock-release of a failed background task is wrong by a couple hours?)

The calculation here should be as good as any existing calculations on this column (as performed in this recipe or in core) -- ie it's OK for simple deployments with relatively consistent timezones, but it's highly suspect for multi-time-zone usage.

All of that really should be a separate issue/bug. But it's a bit relevant in how it influences the interface of $options['release_time']. In this patch:

• $options['release_time'] is not string (Y-m-d H:i:s) because that is ambiguous. (It is unclear whether the timezone of Y-m-d H:i:s should be the current-user-TZ, the queue-worker-TZ, the server-TZ, or GMT. The behavior that would apply at this moment is not the behavior that would be generally good.)
• $options['release_time'] is int (seconds since epoch) because that is unambiguous.

[eileenmcnaughton]

yeah - the column should be a timestamp column - any system-used date column should be