[Catalyst] [Announce] Scheduler 0.03

Andy Grundman andy at hybridized.org
Thu Dec 15 22:06:05 CET 2005

I've released the first version of the Scheduler plugin.  It should incorporate 
most/all of the features that were discussed.


     Catalyst::Plugin::Scheduler - Schedule events to run in a cron-like

         use Catalyst qw/Scheduler/;

         # run remove_sessions in the Cron controller every hour
             at    => '0 * * * *',
             event => '/cron/remove_sessions'

         # Run a subroutine at 4:05am every Sunday
             at    => '5 4 * * sun',
             event => \&do_stuff,

         # A long-running scheduled event that must be triggered
         # manually by an authorized user
             trigger => 'rebuild_search_index',
             event   => '/cron/rebuild_search_index',
         $ wget -q http://www.myapp.com/?schedule_trigger=rebuild_search_index

     This plugin allows you to schedule events to run at recurring intervals.
     Events will run during the first request which meets or exceeds the
     specified time. Depending on the level of traffic to the application,
     events may or may not run at exactly the correct time, but it should be
     enough to satisfy many basic scheduling needs.

     Configuration is optional and is specified in

     Set to 1 to enable logging of events as they are executed. This option
     is enabled by default when running under -Debug mode. Errors are always
     logged regardless of the value of this option.

     The time zone of your system. This will be autodetected where possible,
     or will default to UTC (GMT). You can override the detection by
     providing a valid DateTime time zone string, such as 'America/New_York'.

     The current state of every event is stored in a file. By default this is
     $APP_HOME/scheduler.state. This file is created on the first request if
     it does not already exist.

     The location of the optional YAML event configuration file. By default
     this is $APP_HOME/scheduler.yml.

     This option specifies IP addresses for trusted users. This option
     defaults to Multiple addresses can be specified by using an
     array reference. This option is used for both events where auto_run is
     set to 0 and for manually-triggered events.

         __PACKAGE__->config->{scheduler}->{hosts_allow} = '';
         __PACKAGE__->config->{scheduler}->{hosts_allow} = [

     Events are scheduled by calling the class method "schedule".

             at       => '0 * * * *',
             event    => '/cron/remove_sessions',

         package MyApp::Controller::Cron;

         sub remove_sessions : Private {
             my ( $self, $c ) = @_;


     The time to run an event is specified using crontab(5)-style syntax.

         5 0 * * *      # 5 minutes after midnight, every day
         15 14 1 * *    # run at 2:15pm on the first of every month
         0 22 * * 1-5   # run at 10 pm on weekdays
         5 4 * * sun    # run at 4:05am every Sunday

     From crontab(5):

         field          allowed values
         -----          --------------
         minute         0-59
         hour           0-23
         day of month   1-31
         month          0-12 (or names, see below)
         day of week    0-7 (0 or 7 is Sun, or use names)

     Instead of the first five fields, one of seven special strings may

         string         meaning
         ------         -------
         @yearly        Run once a year, "0 0 1 1 *".
         @annually      (same as @yearly)
         @monthly       Run once a month, "0 0 1 * *".
         @weekly        Run once a week, "0 0 * * 0".
         @daily         Run once a day, "0 0 * * *".
         @midnight      (same as @daily)
         @hourly        Run once an hour, "0 * * * *".

     The event to run at the specified time can be either a Catalyst private
     action path or a coderef. Both types of event methods will receive the
     $c object from the current request, but you must not rely on any
     request-specific information present in $c as it will be from a random
     user request at or near the event's specified run time.

     Important: Methods used for events should be marked "Private" so that
     they can not be executed via the browser.

     The auto_run parameter specifies when the event is allowed to be
     executed. By default this option is set to 1, so the event will be
     executed during the first request that matches the specified time in

     If set to 0, the event will only run when a request is made by a user
     from an authorized address. The purpose of this option is to allow
     long-running tasks to execute only for certain users.

             at       => '0 0 * * *',
             event    => '/cron/rebuild_search_index',
             auto_run => 0,

         package MyApp::Controller::Cron;

         sub rebuild_search_index : Private {
             my ( $self, $c ) = @_;

             # rebuild the search index, this may take a long time

     Now, the search index will only be rebuilt when a request is made from a
     user whose IP address matches the list in the "hosts_allow" config
     option. To run this event, you probably want to ping the app from a cron

         0 0 * * * wget -q http://www.myapp.com/

     To create an event that does not run on a set schedule and must be
     manually triggered, you can specify the "trigger" option instead of

             trigger => 'send_email',
             event   => '/events/send_email',

     The event may then be triggered by a standard web request from an
     authorized user. The trigger to run is specified by using a special GET
     parameter, 'schedule_trigger'; the path requested does not matter.


     By default, manual events may only be triggered by requests made from
     localhost ( To allow other addresses to run events, use the
     configuration option "hosts_allow".

     As an alternative to using the schedule() method, you may define
     scheduled events in an external YAML file. By default, the plugin looks
     for the existence of a file called "schedule.yml" in your application's
     home directory. You can change the filename using the configuration
     option "yaml_file".

     Modifications to this file will be re-read once per minute during the
     normal event checking process.

     Here's an example YAML configuration file with 4 events. Each event is
     denoted with a '-' character, followed by the same parameters used by
     the "schedule" method. Note that coderef events are not supported by the
     YAML file.

         - at: '* * * * *'
           event: /cron/delete_sessions
         - event: /cron/send_email
           trigger: send_email
         - at: '@hourly'
           event: /cron/hourly
         - at: 0 0 * * *
           auto_run: 0
           event: /cron/rebuild_search_index

     All events are run inside of an eval container. This protects the user
     from receiving any error messages or page crashes if an event fails to
     run properly. All event errors are logged, even if logging is disabled.

     Other plugins may register scheduled events if they need to perform
     periodic maintenance. Plugin authors, be sure to inform your users if
     you do this! Events should be registered from a plugin's "setup" method.

         sub setup {
             my $c = shift;

             if ( $c->can('schedule') ) {
                     at    => '0 * * * *',
                     event => \&cleanup,

     The time at which an event will run is determined completely by the
     requests made to the application. Apps with heavy traffic may have
     events run at very close to the correct time, whereas apps with low
     levels of traffic may see events running much later than scheduled. If
     this is a problem, you can use a real cron entry that simply hits your
     application at the desired time.

         0 * * * * wget -q http://www.myapp.com/

     Events which consume a lot of time will slow the request processing for
     the user who triggers the event. For these types of events, you should
     use auto_run => 0 or manual event triggering.

     The plugin only checks once per minute if any events need to be run, so
     the overhead on each request is minimal. On my test server, the
     difference between running with Scheduler and without was only around
     0.02% (0.004 seconds).

     Of course, when a scheduled event runs, performance will depend on
     what's being run in the event.

     Schedule is a class method for adding scheduled events. See the
     "SCHEDULING" section for more information.

     The following methods are extended by this plugin.

         The main scheduling logic takes place during the dispatch phase.




More information about the Catalyst mailing list