sample implementation

I had difficulty using this module not knowing how best to utilize it with other modules. Can we add something like this to a README file:

==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):

/**
 * 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:

  drupal_mail('some-email-id', $to, $subject, $body, $from, $headers);

After:

  job_queue_add('drupal_mail', 'Description of the email process', array('some-email-id', $to, $subject, $body, $from, $headers), '', 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/logs/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:

  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

Thanks for the documentation! I decided to go ahead and put this on the project front page. I did do some editing, such as replacing some uses of "may be" with "is."

how to know the name of the other functions that usually run on cron ?

This ought to be updated to use the relevant code for Drupal 6, which is

  drupal_mail($module, $key, $to, $language, $params = array(), $from = NULL, $send = TRUE)