CakeResque 3.0 : welcoming the Scheduled Jobs

CakeResque 3.0 was just freshly baked. The most important feature of this version is the support of scheduled jobs.

In addition to the possibility of queuing a job for a later execution, you can now specify when to queue the job.

Scheduling jobs

Queuing a job on a future date

You can know specify when to queue the job with CakeResque::enqueueAt(). This function takes 5 arguments :

CakeResque::enqueueAt($time, $queue, $class, $args, $track);

The last 4 arguments are the same arguments as the basic CakeResque::enqueue(); The new argument is the first argument, which is the the date when you want to queue the job. It can be a DateTime object, or simply an integer representing a timestamp.

Example

CakeResque::enqueueAt(
    new DateTime('2012-01-26 15:56:23'),
    'default', // Queue Name
    'MyPlugin.DummyJobShell', // Job classname 
    array(0,1,2) // Various args
);

Queuing a job after a certain time

You can also queue a job after a certain time, for example after 5 minutes, in case you don’t have the exact absolute time, with CakeResque::enqueueIn(). It also takes 5 arguments :

CakeResque::enqueueIn($seconds, $queue, $class, $args, $track);

Like with the CakeResque:enqueueAt(), last 4 arguments are the same as CakeResque::enqueue(), first argument is the number of seconds to wait before queuing the job.

Example

CakeResque::enqueueIn(
    3600, // Queue the job after 1 hour
    'default', // Queue Name
    'MyPlugin.DummyJobShell', // Job classname 
    array(0,1,2) // Various args
);

Limitations

By the worker polling time

Scheduling a job for time X/after Y seconds does not guarantee that the job will run at the specified time. It only means that the job will be added to the specified queue at that time. When will it be executed will depends on the worker polling the queue.

Example

Let’s suppose we have a queue, with a worker polling it each 15 seconds. Let’s say you started the worker precisely at 00 second, so the worker will poll the queue each minutes at 00, 15, 30 and 45 seconds.

If you have scheduled a job for 14:05:04, the job will only be added in the queue at 14:05:04, it has to wait until 14:05:15, for the worker to execute it.

By the Scheduler Worker polling time

Another point to know is that before the job is added to the queue, it ‘sleeps’ in a special queue. A special worker, the Scheduler Worker, will poll that queue to check for due jobs, and add them to the right queue. That Scheduler Worker also have its own pause between each polling (that you can define yourself), set by default to 3 seconds.

Example

With the previous example, the job is scheduled for 14:05:04. The Scheduler worker, that runs each 3 seconds (at 03, 06, 09 seconds, etc) will add it to the queue at 14:05:06, where the regular worker will execute it at 14:05:15. Of course, you can lower the polling time of the Scheduler Worker to 1 second, depending on your need.

Installation

Update the plugin

  • Backup CakeResque’s bootstrap.php file, located in Plugin/CakeResque/Config
  • Download the latest version of CakeResque, uncompress it and replace your current CakeResque folder with the new one. Obviously, folder name should remain ‘CakeResque’.
  • There’s some new settings in the new bootstrap, that goes from line 135 to 177. Copy and paste them to your backup bootstrap.php, then restore it.

Update dependencies

CakeResque 3 makes use of the latest version of php-resque-ex, and the php-resque-ex-scheduler addon.

Updating dependencies are simple, in the terminal, run :

# go to your Plugin/CakeResque directory
cd path/to/Plugin/CakeResque

# OPTION #1
# If you don't have composer installed, install it
curl -s https://getcomposer.org/installer | php
# Then install dependencies
php composer.phar install

# OPTION #2
# If you already have composer installed
composer install

The Scheduler Worker

The Scheduler Worker is a special worker used to moved the jobs in the right queue when they’re due. It must be running to handle scheduled jobs, else these jobs will never be pushed in the right queue, thus never be executed.

To start the scheduler worker, run in the terminal :

cake CakeResque.CakeResque startscheduler

You can also set the polling interval with the -i flag.

cake CakeResque.CakeResque startscheduler -i 3

Unlike the regular worker starting command, the interval flag is the only flag accepted by the startscheduler command. Default value is 3 seconds, that you can edit in the bootstrap, under CakeResque.Scheduler.Worker.interval.

You can only have one scheduler worker. Attempting to start another will fail. If you use the load command to start your worker, the scheduler worker will be started automatically.

This worker can be paused, resumed and stopped like any other worker, with the usual command.

Settings

Refer to bootstrap file for the scheduler worker settings. Scheduler Worker has its own settings.

Scheduler is disabled by default. Enable only if you use it, else the Scheduler Worker will just be a burden.

Other improvement

The stats command

The stats command has been updated with new informations. It now displays the number of jobs in each queues, and notify you when a queue is not monitored by a worker.

It also warn you when there is jobs scheduled, but the Scheduler Worker is not running.

Job tracking

You can track job status like usual. Scheduled jobs are labeled ‘scheduled’.