crm.fsf.org/20131203/files/sites/all/modules-new/civicrm/CRM/Queue/Queue.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2015                                |
   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 array $queueSpec
  50    *   Array with keys:
  51    *   - type: string, required, e.g. "interactive", "immediate", "stomp",
  52    *     "beanstalk"
  53    *   - name: string, required, e.g. "upgrade-tasks"
  54    *   - reset: bool, optional; if a queue is found, then it should be
  55    *     flushed; default to TRUE
  56    *   - (additional keys depending on the queue provider).
  57    */
  58   public function __construct($queueSpec) {
  59     $this->_name = $queueSpec['name'];
  60   }
  61
  62   /**
  63    * Determine the string name of this queue.
  64    *
  65    * @return string
  66    */
  67   public function getName() {
  68     return $this->_name;
  69   }
  70
  71   /**
  72    * Perform any registation or resource-allocation for a new queue
  73    */
  74   public abstract function createQueue();
  75
  76   /**
  77    * Perform any loading or pre-fetch for an existing queue.
  78    */
  79   public abstract function loadQueue();
  80
  81   /**
  82    * Release any resources claimed by the queue (memory, DB rows, etc)
  83    */
  84   public abstract function deleteQueue();
  85
  86   /**
  87    * Check if the queue exists.
  88    *
  89    * @return bool
  90    */
  91   public abstract function existsQueue();
  92
  93   /**
  94    * Add a new item to the queue.
  95    *
  96    * @param mixed $data
  97    *   Serializable PHP object or array.
  98    * @param array $options
  99    *   Queue-dependent options; for example, if this is a
 100    *   priority-queue, then $options might specify the item's priority.
 101    */
 102   public abstract function createItem($data, $options = array());
 103
 104   /**
 105    * Determine number of items remaining in the queue.
 106    *
 107    * @return int
 108    */
 109   public abstract function numberOfItems();
 110
 111   /**
 112    * Get the next item.
 113    *
 114    * @param int $lease_time
 115    *   Seconds.
 116    *
 117    * @return object
 118    *   with key 'data' that matches the inputted data
 119    */
 120   public abstract function claimItem($lease_time = 3600);
 121
 122   /**
 123    * Get the next item, even if there's an active lease
 124    *
 125    * @param int $lease_time
 126    *   Seconds.
 127    *
 128    * @return object
 129    *   with key 'data' that matches the inputted data
 130    */
 131   public abstract function stealItem($lease_time = 3600);
 132
 133   /**
 134    * Remove an item from the queue.
 135    *
 136    * @param object $item
 137    *   The item returned by claimItem.
 138    */
 139   public abstract function deleteItem($item);
 140
 141   /**
 142    * Return an item that could not be processed.
 143    *
 144    * @param object $item
 145    *   The item returned by claimItem.
 146    */
 147   public abstract function releaseItem($item);
 148
 149 }