/* $Id$ */

Job Queue Module
Ported to Drupal 6.x by Ryan Palmer (rypalmer@gmail.com)

--Introduction--

This module can be used by other modules to queue up function calls for execution on cron. The job_queue_add() function 
may be used by any module to add a job to the queue. It is documented as follows (from job_queue.module):

<?php
/**
* Add a job to the queue. The function added will be called in the order it
* was added during cron.
*
* @param $function
*   The function name to call.
* @param $description
*   A human-readable description of the queued job.
* @param $arguments
*   Optional array of arguments to pass to the function.
* @param $file
*   Optional file path which needs to be included for $fucntion.
* @param $no_duplicate
*   If TRUE, do not add the job to the queue if one with the same function and
*   arguments already exists.
*/
function job_queue_add($function, $description, $arguments = array(), $file = '', $no_duplicate = FALSE) {
?>

--Example--

Normally, to send email from Drupal, the drupal_mail function is used directly to send email. If many emails must be 
sent at one time, however, this process may cause Drupal to time out. Instead, job_queue_add() may be used to queue 
the job to eventually be executed as cron runs and the job_queue module processes the job queue.

Before:

<?php
  drupal_mail('example_module', 'notify', $account->mail, user_preferred_language($account), $params);
?>

After:

<?php
  job_queue_add('drupal_mail', 'Description of the email process', array('example_module', 'notify', $account->mail, 
                user_preferred_language($account), $params), '', TRUE);
?>

As we can see, the first argument is the name of the function we would have otherwise executed, the next is a 
description to give this job, and the next is the array of arguments that you otherwise would have executed the 
original function with. The last two arguments are optional, but in this case it was decided to include the TRUE 
argument to insure that duplicate emails are not accidentally queued.

From here, we can see the job appear in the job queue:
http://www.mysite.com/admin/reports/job_queue

As cron is triggered, the queue will be processed and the jobs removed from it.

--Setting Priorities--

Modules may also define their own function priorities. A priority weight (from -10 to 10) may be set to determine 
which jobs get priority over others, based on their executing function.

The hook hook_job_queue_functions() may be used to define such functions to prioritize:

Example:
<?php
  function mymodule_job_queue_functions() {
    $function['drupal_mail'] = array('title' => 'Drupal mail');
    return $function;
  }
?>

Once defined initially, the function's priority may be configured here:
http://www.mysite.com/admin/settings/job_queue