[Catalyst] [RFC] C::P::Scheduler - cron-like scheduling of events

[Andy Grundman]

I have a need for a simple scheduling plugin to do things like clean up database 
sessions, so I roughed out docs for a new plugin called Scheduler.  If you've 
got any thoughts or suggestions, please let me know. :)

-Andy

=head1 NAME

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

=head1 SYNOPSIS

     use Catalyst qw/Scheduler/;

     # enable logging
     __PACKAGE__->config->{scheduler}->{logging} = 1;

     # run remove_sessions in the Cron controller every hour
     __PACKAGE__->schedule(
         at    => '0 * * * *',
         event => '/cron/remove_sessions'
     );

     # Run a coderef at 4:05am every Sunday
     __PACKAGE__->schedule(
         at    => '5 4 * * sun',
         event => \&do_stuff,
     );

=head1 DESCRIPTION

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.

=head1 CONFIGURATION

Configuration is optional and is specified in MyApp->config->{scheduler}.

=head2 logging

Set to 1 to enable logging of events as they are executed.  This option is
enabled by default when running under -Debug mode.

=head2 state_file

The current state of every event is stored in a file.  By default this is
$APP_HOME/scheduler.state.  If this file cannot be read or created at
startup, your app will die.

=head1 SCHEDULING

Events are scheduled by calling the class method C<schedule> with two
parameters: C<at> and C<event>.

=head2 at

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 eight special strings may appear:

     string         meaning
     ------         -------
     @reboot        Run once, at startup.
     @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 * * * *".

=head2 event

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.

=head1 CAVEATS

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 are
encouraged to use a real cron scheduler.

Events which consume a lot of time will slow the request processing for the
user who triggers the event.  Long-running tasks should not be scheduled using
this plugin.