annotate core/lib/Drupal/Core/Queue/QueueInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents 129ea1e6d783
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 namespace Drupal\Core\Queue;
Chris@0 4
Chris@0 5 /**
Chris@0 6 * Interface for a queue.
Chris@0 7 *
Chris@0 8 * Classes implementing this interface will do a best effort to preserve order
Chris@0 9 * in messages and to execute them at least once.
Chris@0 10 *
Chris@0 11 * @ingroup queue
Chris@0 12 */
Chris@0 13 interface QueueInterface {
Chris@0 14
Chris@0 15 /**
Chris@0 16 * Adds a queue item and store it directly to the queue.
Chris@0 17 *
Chris@0 18 * @param $data
Chris@0 19 * Arbitrary data to be associated with the new task in the queue.
Chris@0 20 *
Chris@0 21 * @return
Chris@0 22 * A unique ID if the item was successfully created and was (best effort)
Chris@0 23 * added to the queue, otherwise FALSE. We don't guarantee the item was
Chris@0 24 * committed to disk etc, but as far as we know, the item is now in the
Chris@0 25 * queue.
Chris@0 26 */
Chris@0 27 public function createItem($data);
Chris@0 28
Chris@0 29 /**
Chris@0 30 * Retrieves the number of items in the queue.
Chris@0 31 *
Chris@0 32 * This is intended to provide a "best guess" count of the number of items in
Chris@0 33 * the queue. Depending on the implementation and the setup, the accuracy of
Chris@0 34 * the results of this function may vary.
Chris@0 35 *
Chris@0 36 * e.g. On a busy system with a large number of consumers and items, the
Chris@0 37 * result might only be valid for a fraction of a second and not provide an
Chris@0 38 * accurate representation.
Chris@0 39 *
Chris@17 40 * @return int
Chris@0 41 * An integer estimate of the number of items in the queue.
Chris@0 42 */
Chris@0 43 public function numberOfItems();
Chris@0 44
Chris@0 45 /**
Chris@0 46 * Claims an item in the queue for processing.
Chris@0 47 *
Chris@0 48 * @param $lease_time
Chris@0 49 * How long the processing is expected to take in seconds, defaults to an
Chris@0 50 * hour. After this lease expires, the item will be reset and another
Chris@0 51 * consumer can claim the item. For idempotent tasks (which can be run
Chris@0 52 * multiple times without side effects), shorter lease times would result
Chris@0 53 * in lower latency in case a consumer fails. For tasks that should not be
Chris@0 54 * run more than once (non-idempotent), a larger lease time will make it
Chris@0 55 * more rare for a given task to run multiple times in cases of failure,
Chris@0 56 * at the cost of higher latency.
Chris@0 57 *
Chris@0 58 * @return
Chris@0 59 * On success we return an item object. If the queue is unable to claim an
Chris@0 60 * item it returns false. This implies a best effort to retrieve an item
Chris@0 61 * and either the queue is empty or there is some other non-recoverable
Chris@0 62 * problem.
Chris@0 63 *
Chris@0 64 * If returned, the object will have at least the following properties:
Chris@0 65 * - data: the same as what what passed into createItem().
Chris@0 66 * - item_id: the unique ID returned from createItem().
Chris@0 67 * - created: timestamp when the item was put into the queue.
Chris@0 68 */
Chris@0 69 public function claimItem($lease_time = 3600);
Chris@0 70
Chris@0 71 /**
Chris@0 72 * Deletes a finished item from the queue.
Chris@0 73 *
Chris@0 74 * @param $item
Chris@0 75 * The item returned by \Drupal\Core\Queue\QueueInterface::claimItem().
Chris@0 76 */
Chris@0 77 public function deleteItem($item);
Chris@0 78
Chris@0 79 /**
Chris@0 80 * Releases an item that the worker could not process.
Chris@0 81 *
Chris@0 82 * Another worker can come in and process it before the timeout expires.
Chris@0 83 *
Chris@0 84 * @param $item
Chris@0 85 * The item returned by \Drupal\Core\Queue\QueueInterface::claimItem().
Chris@0 86 *
Chris@0 87 * @return bool
Chris@0 88 * TRUE if the item has been released, FALSE otherwise.
Chris@0 89 */
Chris@0 90 public function releaseItem($item);
Chris@0 91
Chris@0 92 /**
Chris@0 93 * Creates a queue.
Chris@0 94 *
Chris@0 95 * Called during installation and should be used to perform any necessary
Chris@0 96 * initialization operations. This should not be confused with the
Chris@0 97 * constructor for these objects, which is called every time an object is
Chris@0 98 * instantiated to operate on a queue. This operation is only needed the
Chris@0 99 * first time a given queue is going to be initialized (for example, to make
Chris@0 100 * a new database table or directory to hold tasks for the queue -- it
Chris@0 101 * depends on the queue implementation if this is necessary at all).
Chris@0 102 */
Chris@0 103 public function createQueue();
Chris@0 104
Chris@0 105 /**
Chris@0 106 * Deletes a queue and every item in the queue.
Chris@0 107 */
Chris@0 108 public function deleteQueue();
Chris@0 109
Chris@0 110 }