interface DrupalQueueInterface

interface DrupalQueueInterface  {
 
 /**
 * Add a queue item and store it directly to the queue.
 *
 * @param $data
 * Arbitrary data to be associated with the new task in the queue.
 * @return
 * TRUE if the item was successfully created and was (best effort) added
 * to the queue, otherwise FALSE. We don't guarantee the item was
 * committed to disk etc, but as far as we know, the item is now in the
 * queue.
 */
 public function createItem($data);
 
 /**
 * Retrieve the number of items in the queue.
 *
 * This is intended to provide a "best guess" count of the number of items in
 * the queue. Depending on the implementation and the setup, the accuracy of
 * the results of this function may vary.
 *
 * e.g. On a busy system with a large number of consumers and items, the
 * result might only be valid for a fraction of a second and not provide an
 * accurate representation.
 *
 * @return
 * An integer estimate of the number of items in the queue.
 */
 public function numberOfItems();
 
 /**
 * Claim an item in the queue for processing.
 *
 * @param $lease_time
 * How long the processing is expected to take in seconds, defaults to an
 * hour. After this lease expires, the item will be reset and another
 * consumer can claim the item. For idempotent tasks (which can be run
 * multiple times without side effects), shorter lease times would result
 * in lower latency in case a consumer fails. For tasks that should not be
 * run more than once (non-idempotent), a larger lease time will make it
 * more rare for a given task to run multiple times in cases of failure,
 * at the cost of higher latency.
 * @return
 * On success we return an item object. If the queue is unable to claim an
 * item it returns false. This implies a best effort to retrieve an item
 * and either the queue is empty or there is some other non-recoverable
 * problem.
 */
 public function claimItem($lease_time = 3600);
 
 /**
 * Delete a finished item from the queue.
 *
 * @param $item
 * The item returned by DrupalQueueInterface::claimItem().
 */
 public function deleteItem($item);
 
 /**
 * Release an item that the worker could not process, so another
 * worker can come in and process it before the timeout expires.
 *
 * @param $item
 * @return boolean
 */
 public function releaseItem($item);
 
 /**
 * Create a queue.
 *
 * Called during installation and should be used to perform any necessary
 * initialization operations. This should not be confused with the
 * constructor for these objects, which is called every time an object is
 * instantiated to operate on a queue. This operation is only needed the
 * first time a given queue is going to be initialized (for example, to make
 * a new database table or directory to hold tasks for the queue -- it
 * depends on the queue implementation if this is necessary at all).
 */
 public function createQueue();
 
 /**
 * Delete a queue and every item in the queue.
 */
 public function deleteQueue();
}