= 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

[[Image(sfJobQueuePlugin_job_election.png, left)]]

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.