www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Queue/QueueInterface.php

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