queue_example.module

<?php
/**
 * @file
 * Hook implementations for the Queue Example module.
 */

/**
 * @defgroup queue_example Example: Queue
 * @ingroup examples
 * @{
 * This example demonstrates how to use the queue API.
 *
 * The queue API provides a traditional FIFO (first-in-first-out) queue, but
 * also provides the concepts of:
 * - "Creating" a queued item, which means inserting it into a queue.
 * - "Claiming" a queued item, which essentially means requesting the next item
 *   from the queue and holding a lock on that item for a specified period of
 *   time.
 * - "Releasing" an item, which means giving up a claim but leaving the item in
 *   the queue.
 * - "Deleting" an item, which means finally removing it from the queue.
 *
 * This example demonstrates only basic queue functionality; it will use the
 * default queue implementation, which is SystemQueue, that uses the persistent
 * database storage.
 *
 * Further resources include the limited @link queue @endlink documentation and
 * @link http://www.ent.iastate.edu/it/Batch_and_Queue.pdf Batch vs. Queue: an API Smackdown @endlink
 * by John VanDyk.
 *
 * @see system.queue.inc
 */

/**
 * Implements hook_menu().
 */
function queue_example_menu() {
  $items = array();
  $items['queue_example/insert_remove'] = array(
    'title' => 'Queue Example: Insert and remove',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('queue_example_add_remove_form'),
    'access callback' => TRUE,
  );

  return $items;
}

/**
 * Form generator for managing the queue.
 *
 * Provides an interface to add items to the queue, to retrieve (claim)
 * an item from the head of the queue, and to claim and delete. Also
 * allows the user to run cron manually, so that claimed items can be
 * released.
 */
function queue_example_add_remove_form($form, &$form_state) {
  // Simple counter that makes it possible to put auto-incrementing default
  // string into the string to insert.
  if (empty($form_state['storage']['insert_counter'])) {
    $form_state['storage']['insert_counter'] = 1;
  }

  $queue_name = !empty($form_state['values']['queue_name']) ? $form_state['values']['queue_name'] : 'queue_example_first_queue';
  $items = queue_example_retrieve_queue($queue_name);

  // Add CSS to make the form a bit denser.
  $form['#attached']['css'] = array(backdrop_get_path('module', 'queue_example') . '/queue_example.css');

  $form['help'] = array(
    '#type' => 'markup',
    '#markup' => '<div>' . t('This page is an interface on the Backdrop queue API. You can add new items to the queue, "claim" one (retrieve the next item and keep a lock on it), and delete one (remove it from the queue). Note that claims are not expired until cron runs, so there is a special button to run cron to perform any necessary expirations.') . '</div>',
  );

  $form['queue_name'] = array(
    '#type' => 'select',
    '#title' => t('Choose queue to examine'),
    '#options' => backdrop_map_assoc(array('queue_example_first_queue', 'queue_example_second_queue')),
    '#default_value' => $queue_name,
  );
  $form['queue_show'] = array(
    '#type' => 'submit',
    '#value' => t('Show queue'),
    '#submit' => array('queue_example_show_queue'),
  );
  $form['status_fieldset'] = array(
    '#type' => 'fieldset',
    '#title' => t('Queue status for @name', array('@name' => $queue_name)),
    '#collapsible' => TRUE,
  );
  $form['status_fieldset']['status'] = array(
    '#type' => 'markup',
    '#markup' => theme('queue_items', array('items' => $items)),
  );
  $form['insert_fieldset'] = array(
    '#type' => 'fieldset',
    '#title' => t('Insert into @name', array('@name' => $queue_name)),
  );
  $form['insert_fieldset']['string_to_add'] = array(
    '#type' => 'textfield',
    '#size' => 10,
    '#default_value' => t('item @counter', array('@counter' => $form_state['storage']['insert_counter'])),
  );
  $form['insert_fieldset']['add_item'] = array(
    '#type' => 'submit',
    '#value' => t('Insert into queue'),
    '#submit' => array('queue_example_add_remove_form_insert'),
  );
  $form['claim_fieldset'] = array(
    '#type' => 'fieldset',
    '#title' => t('Claim from queue'),
    '#collapsible' => TRUE,
  );

  $form['claim_fieldset']['claim_time'] = array(
    '#type' => 'radios',
    '#title' => t('Claim time, in seconds'),
    '#options' => array(
      0 => t('none'),
      5 => t('5 seconds'),
      60 => t('60 seconds'),
    ),
    '#description' => t('This time is only valid if cron runs during this time period. You can run cron manually below.'),
    '#default_value' => !empty($form_state['values']['claim_time']) ? $form_state['values']['claim_time'] : 5,
  );
  $form['claim_fieldset']['claim_item'] = array(
    '#type' => 'submit',
    '#value' => t('Claim the next item from the queue'),
    '#submit' => array('queue_example_add_remove_form_claim'),
  );
  $form['claim_fieldset']['claim_and_delete_item'] = array(
    '#type' => 'submit',
    '#value' => t('Claim the next item and delete it'),
    '#submit' => array('queue_example_add_remove_form_delete'),
  );
  $form['claim_fieldset']['run_cron'] = array(
    '#type' => 'submit',
    '#value' => t('Run cron manually to expire claims'),
    '#submit' => array('queue_example_add_remove_form_run_cron'),
  );
  $form['delete_queue'] = array(
    '#type' => 'submit',
    '#value' => t('Delete the queue and items in it'),
    '#submit' => array('queue_example_add_remove_form_clear_queue'),
  );
  return $form;
}

/**
 * Submit function for the insert-into-queue button.
 */
function queue_example_add_remove_form_insert($form, &$form_state) {
  // Get a queue (of the default type) called 'queue_example_queue'.
  // If the default queue class is SystemQueue this creates a queue that stores
  // its items in the database.
  $queue = BackdropQueue::get($form_state['values']['queue_name']);
  // There is no harm in trying to recreate existing.
  $queue->createQueue();

  // Queue the string.
  $queue->createItem($form_state['values']['string_to_add']);
  $count = $queue->numberOfItems();
  backdrop_set_message(t('Queued your string (@string_to_add). There are now @count items in the queue.', array('@count' => $count, '@string_to_add' => $form_state['values']['string_to_add'])));
  // Setting 'rebuild' to TRUE allows us to keep information in $form_state.
  $form_state['rebuild'] = TRUE;
  // Unsetting the string_to_add allows us to set the incremented default value
  // for the user so they don't have to type anything.
  unset($form_state['input']['string_to_add']);
  $form_state['storage']['insert_counter']++;
}

/**
 * Submit function for the show-queue button.
 */
function queue_example_show_queue($form, &$form_state) {
  $queue = BackdropQueue::get($form_state['values']['queue_name']);
  // There is no harm in trying to recreate existing.
  $queue->createQueue();

  // Get the number of items.
  $count = $queue->numberOfItems();

  // Update the form item counter.
  $form_state['storage']['insert_counter'] = $count + 1;

  // Unset the string_to_add textbox.
  unset($form_state['input']['string_to_add']);

  $form_state['rebuild'] = TRUE;
}

/**
 * Submit function for the "claim" button.
 *
 * Claims (retrieves) an item from the queue and reports the results.
 */
function queue_example_add_remove_form_claim($form, &$form_state) {
  $queue = BackdropQueue::get($form_state['values']['queue_name']);
  // There is no harm in trying to recreate existing.
  $queue->createQueue();
  $item = $queue->claimItem($form_state['values']['claim_time']);
  $count = $queue->numberOfItems();
  if (!empty($item)) {
    backdrop_set_message(
      t('Claimed item id=@item_id string=@string for @seconds seconds. There are @count items in the queue.',
        array(
          '@count' => $count,
          '@item_id' => $item->item_id,
          '@string' => $item->data,
          '@seconds' => $form_state['values']['claim_time'],
        )
      )
    );
  }
  else {
    backdrop_set_message(t('There were no items in the queue available to claim. There are @count items in the queue.', array('@count' => $count)));
  }
  $form_state['rebuild'] = TRUE;
}

/**
 * Submit function for "Claim and delete" button.
 */
function queue_example_add_remove_form_delete($form, &$form_state) {
  $queue = BackdropQueue::get($form_state['values']['queue_name']);
  // There is no harm in trying to recreate existing.
  $queue->createQueue();
  $count = $queue->numberOfItems();
  $item = $queue->claimItem(60);
  if (!empty($item)) {
    backdrop_set_message(
      t('Claimed and deleted item id=@item_id string=@string for @seconds seconds. There are @count items in the queue.',
        array(
          '@count' => $count,
          '@item_id' => $item->item_id,
          '@string' => $item->data,
          '@seconds' => $form_state['values']['claim_time'],
        )
      )
    );
    $queue->deleteItem($item);
    $count = $queue->numberOfItems();
    backdrop_set_message(t('There are now @count items in the queue.', array('@count' => $count)));
  }
  else {
    $count = $queue->numberOfItems();
    backdrop_set_message(t('There were no items in the queue available to claim/delete. There are currently @count items in the queue.', array('@count' => $count)));
  }
  $form_state['rebuild'] = TRUE;
}

/**
 * Submit function for "run cron" button.
 *
 * Runs cron (to release expired claims) and reports the results.
 */
function queue_example_add_remove_form_run_cron($form, &$form_state) {
  backdrop_cron_run();
  $queue = BackdropQueue::get($form_state['values']['queue_name']);
  // There is no harm in trying to recreate existing.
  $queue->createQueue();
  $count = $queue->numberOfItems();
  backdrop_set_message(t('Ran cron. If claimed items expired, they should be expired now. There are now @count items in the queue', array('@count' => $count)));
  $form_state['rebuild'] = TRUE;
}

/**
 * Submit handler for clearing/deleting the queue.
 */
function queue_example_add_remove_form_clear_queue($form, &$form_state) {
  $queue = BackdropQueue::get($form_state['values']['queue_name']);
  $queue->deleteQueue();
  backdrop_set_message(t('Deleted the @queue_name queue and all items in it', array('@queue_name' => $form_state['values']['queue_name'])));
}

/**
 * Retrieves the queue from the database for display purposes only.
 *
 * It is not recommended to access the database directly, and this is only here
 * so that the user interface can give a good idea of what's going on in the
 * queue.
 *
 * @param array $queue_name
 *   The name of the queue from which to fetch items.
 */
function queue_example_retrieve_queue($queue_name) {
  $items = array();
  $result = db_query("SELECT item_id, data, expire, created FROM {queue} WHERE name = :name ORDER BY item_id",
    array(':name' => $queue_name),
    array('fetch' => PDO::FETCH_ASSOC));
  foreach ($result as $item) {
    $items[] = $item;
  }
  return $items;
}

/**
 * Themes the queue display.
 *
 * Again, this is not part of the demonstration of the queue API, but is here
 * just to make the user interface more understandable.
 *
 * @param array $variables
 *   Our variables.
 */
function theme_queue_items($variables) {
  $items = $variables['items'];
  $rows = array();
  foreach ($items as &$item) {
    if ($item['expire'] > 0) {
      $item['expire'] = t("Claimed: expires %expire", array('%expire' => date('r', $item['expire'])));
    }
    else {
      $item['expire'] = t('Unclaimed');
    }
    $item['created'] = date('r', $item['created']);
    $item['content'] = check_plain(unserialize($item['data']));
    unset($item['data']);
    $rows[] = $item;
  }
  if (!empty($rows)) {
    $header = array(
      t('Item ID'),
      t('Claimed/Expiration'),
      t('Created'),
      t('Content/Data'),
    );
    $output = theme('table', array('header' => $header, 'rows' => $rows));
    return $output;
  }
  else {
    return t('There are no items in the queue.');
  }
}

/**
 * Implements hook_theme().
 */
function queue_example_theme() {
  return array(
    'queue_items' => array(
      'variables' => array('items' => NULL),
    ),
  );
}
/**
 * @} End of "defgroup queue_example".
 */