CRM/Queue/Queue.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  * A queue is an object (usually backed by some persistent data store)
  30  * which stores a list of tasks or messages for use by other processes.
  31  *
  32  * This would ideally be an interface, but it's handy to specify the
  33  * "function __construct()" and the "$name" handling
  34  *
  35  * Note: This interface closely parallels the DrupalQueueInterface.
  36  */
  37 abstract class CRM_Queue_Queue {
  38
  39   /**
  40    * @var string
  41    */
  42   private $_name;
  43
  44   /**
  45    * Create a reference to queue. After constructing the queue, one should
  46    * usually call createQueue (if it's a new queue) or loadQueue (if it's
  47    * known to be an existing queue).
  48    *
  49    * @param $queueSpec, array with keys:
  50    *   - type: string, required, e.g. "interactive", "immediate", "stomp", "beanstalk"
  51    *   - name: string, required, e.g. "upgrade-tasks"
  52    *   - reset: bool, optional; if a queue is found, then it should be flushed; default to TRUE
  53    *   - (additional keys depending on the queue provider)
  54    */ function __construct($queueSpec) {
  55     $this->_name = $queueSpec['name'];
  56   }
  57
  58   /**
  59    * Determine the string name of this queue
  60    *
  61    * @return string
  62    */
  63   function getName() {
  64     return $this->_name;
  65   }
  66
  67   /**
  68    * Perform any registation or resource-allocation for a new queue
  69    */
  70   abstract function createQueue();
  71
  72   /**
  73    * Perform any loading or pre-fetch for an existing queue.
  74    */
  75   abstract function loadQueue();
  76
  77   /**
  78    * Release any resources claimed by the queue (memory, DB rows, etc)
  79    */
  80   abstract function deleteQueue();
  81
  82   /**
  83    * Check if the queue exists
  84    *
  85    * @return bool
  86    */
  87   abstract function existsQueue();
  88
  89   /**
  90    * Add a new item to the queue
  91    *
  92    * @param $data serializable PHP object or array
  93    * @param array|\queue $options queue-dependent options; for example, if this is a
  94    *   priority-queue, then $options might specify the item's priority
  95    *
  96    * @return bool, TRUE on success
  97    */
  98   abstract function createItem($data, $options = array());
  99
 100   /**
 101    * Determine number of items remaining in the queue
 102    *
 103    * @return int
 104    */
 105   abstract function numberOfItems();
 106
 107   /**
 108    * Get the next item
 109    *
 110    * @param int|\seconds $lease_time seconds
 111    *
 112    * @return object with key 'data' that matches the inputted data
 113    */
 114   abstract function claimItem($lease_time = 3600);
 115
 116   /**
 117    * Get the next item, even if there's an active lease
 118    *
 119    * @param int|\seconds $lease_time seconds
 120    *
 121    * @return object with key 'data' that matches the inputted data
 122    */
 123   abstract function stealItem($lease_time = 3600);
 124
 125   /**
 126    * Remove an item from the queue
 127    *
 128    * @param $item The item returned by claimItem
 129    */
 130   abstract function deleteItem($item);
 131
 132   /**
 133    * Return an item that could not be processed
 134    *
 135    * @param $item The item returned by claimItem
 136    *
 137    * @return bool
 138    */
 139   abstract function releaseItem($item);
 140 }
 141