# sfJobQueuePlugin

## Introduction

This plugins enables job queues into Symfony. It includes all the common job queues tasks (start, stop, scheduling through job election strategies, etc.), command line tasks, and a graphical interface for managing queues and jobs. Using a job queue can be useful when asynchronised server-side operations have to be performed (periodically grabbing a RSS feed, automatically sending emails, etc.) or in environments without a cron access.

A "job" is a task that has to be done. In this plugin, it is modeled as a call ton a JobHandler, which understands the parameters associated to the job in order to perform a dedicated action.
A "job queue" is a group of jobs to be run, eventually several times, associated to a job election strategy. In this plugin, one job queue can only run one job at a time.

## Features

  * multi-queues support
  * one given queue can contain heterogeneous job types
  * scheduling (job election) strategy abstraction
  * CLI tasks
  * Queue and jobs management graphical module (job status visualisation only)

## Get it installed

  * go to your project's root

  * Install the plugin:
       
         ./symfony plugin-install http://plugins.symfony-project.com/sfJobQueuePlugin
       

  * rebuild the model:
       
         ./symfony propel-build-all
       

  * clear cache:
       
         ./symfony cc
       


## Usage

### Creating a queue

In order to create a job queue, you must first activate the administration module. You can then create a job queue by defining:
  * its name
  * its job election strategy (either FIFO or priority-based)

You usually won't need it, but it is also possible to create job queues dynamically, directly from your application's code:
    
    [php]
    <?php
    $queue = new sfJobQueue();
    $queue->setName('RSS grabbing queue');
    $queue->setSchedulerName('fifo');
    $queue->save();
    

By default, the job queue is stopped when created. In order it to get active, you need to start it.

### Running a job queue

For the moment, running a job queue can only be done through the command line interface:
    
      ./symfony sfqueue-start-queue YOUR_APP_NAME QUEUE_NAME
    
So, for instance :
    
      ./symfony sfqueue-start-queue frontend 'RSS grabbing queue'
    

### Adding a job to the JobQueue

Adding a job to one job queue is rather simple. You only have to give the type of the job which has to be created, and set its execution parameters.
    
    [php]
    <?php
    $queue->addJob('mailing', array('to' => 'xavier@lacot.org', 'topic' => 'Testing the MailingJobQueue :)'));
    

## Job parameters

A job queue can be tweaked using several parameters:
  * scheduler_name: the scheduler name defines the policy of job election. For instance, with a "fifo" scheduler, the oldest eligible job will be the one who will be processed next. With a "priority" scheduler, the eligible job with the highest priority will be the first out.
  * polling_delay: time between the end of the execution of one job, and the following job election

![sfJobQueuePlugin_job_election.png](http://trac.symfony-project.org/attachment/wiki/sfJobQueuePlugin/sfJobQueuePlugin_job_election.png?format=raw)

At the job level, it is also possible to set some general execution parameters:
  * max_tries:
  * retry_delay: retry delay, in seconds (minimal delay between two tries of the same job)
  * priority: priority : from 0 to 9 (lower to higher)
  * params: an array of parameters for the job execution

## API

sfJobQueue:
  * **addJob($type = '', $options = null)** - Creates a new job in the queue
  * **getNbActiveJobs()** - Returns the number of jobs to be done
  * **getNbCompletedJobs()** - Returns the number of completed jobs
  * **getStatusText()** - Returns the status of the queue, as a text
  * **isRunning()** - Indicates whether the queue is running or not
  * **run()** - Runs the queue

sfJob:
  * **getStatusText()** - Returns the status of the job, as a text
  * **run()** - Runs the job

## Unit testing

To be done.

## Roadmap

  * "Hello world" sample job
  * start/stop a queue from the graphical interface
  * have several jobs running at one time
  * unit-testing
  * job reporting hooks (measure job)

Long term runners might want to see:
  * integration with http://yowl.googlecode.com/svn/trunk/test/test-yowl.html
  * exposition to Web services

## Bibliograhy

  * http://en.wikipedia.org/wiki/Queue_%28data_structure%29
  * http://en.wikipedia.org/wiki/FIFO
  * http://en.wikipedia.org/wiki/Priority_queue

## License and credits

This plugin is licensed under the MIT license and maintained by Xavier Lacot (xavier@lacot.org). External contributions and comments are welcome !

## Changelog

### version 0.1 - 2007-09-17

Initial public release.