This plugin is deprecated and is not maintained anymore.
Please rather use Gearman or comparable things, in order to manage asynchronous tasks.
See http://www.symfony-project.org/plugins/sfGearmanPlugin for more informations
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
$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
$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
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.
