CRM/Queue/Queue.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  * A queue is an object (usually backed by some persistent data store)
  14  * which stores a list of tasks or messages for use by other processes.
  15  *
  16  * This would ideally be an interface, but it's handy to specify the
  17  * "function __construct()" and the "$name" handling
  18  *
  19  * Note: This interface closely parallels the DrupalQueueInterface.
  20  */
  21 abstract class CRM_Queue_Queue {
  22
  23   /**
  24    * @var string
  25    */
  26   private $_name;
  27
  28   /**
  29    * Create a reference to queue. After constructing the queue, one should
  30    * usually call createQueue (if it's a new queue) or loadQueue (if it's
  31    * known to be an existing queue).
  32    *
  33    * @param array $queueSpec
  34    *   Array with keys:
  35    *   - type: string, required, e.g. "interactive", "immediate", "stomp",
  36    *     "beanstalk"
  37    *   - name: string, required, e.g. "upgrade-tasks"
  38    *   - reset: bool, optional; if a queue is found, then it should be
  39    *     flushed; default to TRUE
  40    *   - (additional keys depending on the queue provider).
  41    */
  42   public function __construct($queueSpec) {
  43     $this->_name = $queueSpec['name'];
  44   }
  45
  46   /**
  47    * Determine the string name of this queue.
  48    *
  49    * @return string
  50    */
  51   public function getName() {
  52     return $this->_name;
  53   }
  54
  55   /**
  56    * Perform any registation or resource-allocation for a new queue
  57    */
  58   abstract public function createQueue();
  59
  60   /**
  61    * Perform any loading or pre-fetch for an existing queue.
  62    */
  63   abstract public function loadQueue();
  64
  65   /**
  66    * Release any resources claimed by the queue (memory, DB rows, etc)
  67    */
  68   abstract public function deleteQueue();
  69
  70   /**
  71    * Check if the queue exists.
  72    *
  73    * @return bool
  74    */
  75   abstract public function existsQueue();
  76
  77   /**
  78    * Add a new item to the queue.
  79    *
  80    * @param mixed $data
  81    *   Serializable PHP object or array.
  82    * @param array $options
  83    *   Queue-dependent options; for example, if this is a
  84    *   priority-queue, then $options might specify the item's priority.
  85    */
  86   abstract public function createItem($data, $options = []);
  87
  88   /**
  89    * Determine number of items remaining in the queue.
  90    *
  91    * @return int
  92    */
  93   abstract public function numberOfItems();
  94
  95   /**
  96    * Get the next item.
  97    *
  98    * @param int $lease_time
  99    *   Seconds.
 100    *
 101    * @return object
 102    *   with key 'data' that matches the inputted data
 103    */
 104   abstract public function claimItem($lease_time = 3600);
 105
 106   /**
 107    * Get the next item, even if there's an active lease
 108    *
 109    * @param int $lease_time
 110    *   Seconds.
 111    *
 112    * @return object
 113    *   with key 'data' that matches the inputted data
 114    */
 115   abstract public function stealItem($lease_time = 3600);
 116
 117   /**
 118    * Remove an item from the queue.
 119    *
 120    * @param object $item
 121    *   The item returned by claimItem.
 122    */
 123   abstract public function deleteItem($item);
 124
 125   /**
 126    * Return an item that could not be processed.
 127    *
 128    * @param object $item
 129    *   The item returned by claimItem.
 130    */
 131   abstract public function releaseItem($item);
 132
 133 }