Drupal batch and queue API

Nov 19th, 2012

Good docs for the batch API are here: https://api.drupal.org/api/drupal/includes%21form.inc/group/batch/7.x

The Drupal.org Batch API Overview page is another good resource.

Old Notes below:

Queue

Methods

* createQueue() 
* deleteQueue()

* createItem($data)
* deleteItem()

* claimItem($seconds)
* releaseItem($item)

* numberOfItems()
** don't use because might not be accurate if there are multiple consumers using the same queue

Queue batch classes: BatchQueue and BatchMemoryQueue extend the base classes

* no concept of lease time
* FIFO

SystemQueue and MemoryQueue classes

* SystemQueue
** mysql; stored in the queue table
* MemoryQueue
** fast but not persistent; can only use in one request
* SystemQueue and MemoryQueue do not guarantee that you will pull out items in the same order that you put them in
** Most of the time the order is preserved but not if there are multiple pluggable backends or multiple consumers of the queue

Examples

<?php
// Basic example
// below code is the same as:
// $queue = new SystemQueue('tofu sandwich');
// however, the default Queue is set in a system variable;
//   ie. variable_get('queue_default_class', 'SystemQueue')
// there are pluggable queue systems, like beanstalk, that will change this
// you can also make your own queue class that extends a default queue class and then
//   variable_set('queue_class_tofu_sandwich', 'OtherQueue');
$queue = DrupalQueue::get('tofu sandwich'); // create a queue
$queue->createQueue(); // this doesn't really do anything but is necessary and sort of provides a hook that other modules can use
// add things to the queue
$things = array('bread', 'tofu', 'provolone', 'sprouts'); 
foreach ($things as $item) {
  $queue->createItem($item);
}
drupal_set_message('Queued up @count items', array('%count' => $count));
 
// get the items out and store them in an array
$items = array();
while ($item = $queue-claimItem()){
  $message  .= $item->item_id . ':' .
               $item->data    . '; ';
  $items[] = $item;
}
drupal_set_message('Queue contains' . check_plain($message));
 
// release the items
foreach ($items as $item) {
  $queue->releaseItem($item);
}
?>

Inspecting an $item

<?php
stdClass Object(
  [item_id] => 3
  [data] => sprouts
  [created] => 1231231234
  [expire] => 1242311231
)
?>

Batch

<?php
function batchler_form($form, &$form_state) {
  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Begin'),
  );
  return $form;
}
 
function batchler_form_submit($form, &$form_state) {
  $batch  = array(
    'title' => t('Batching'),
    'operations' => array(
      array('batchler_callback1', array()),
      array('batchler_callback2', array('param 1', 'param 2')), 
    ),
  );
  batch_set($batch);
}
 
function batchler_callback1(&$context) {
  drupal_set_message('batchler_callback1 got called');
}
 
function batchler_callback2($p1, $p2, &$context) {
  if (!isset($context['sandbox']['iteration'])){
    $context['sandbox']['iteration'] = 0;
  }
  $context['sandbox']['iteration']++;
  $context['finished'] = $context['sandbox']['iteration']/10000;
}
 
?>

Internal References

Drupal batch processes in an update hook

External References

https://www.drupal.org/node/180528
https://api.drupal.org/api/drupal/includes%21form.inc/group/batch/7.x

Article Type

General