Provided by: libcatalyst-plugin-scheduler-perl_0.10-1_all bug

NAME

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

SYNOPSIS

           use Catalyst qw/Scheduler/;

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

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

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

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.

CONFIGURATION

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

   logging
       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.

   time_zone
       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'.

   state_file
       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.

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

   hosts_allow
       This option specifies IP addresses for trusted users.  This option defaults to 127.0.0.1.
       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} = '192.168.1.1';
           __PACKAGE__->config->{scheduler}->{hosts_allow} = [
               '127.0.0.1',
               '192.168.1.1'
           ];

SCHEDULING

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

           MyApp->schedule(
               at       => '0 * * * *',
               event    => '/cron/remove_sessions',
           );

           package MyApp::Controller::Cron;

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

               $c->delete_expired_sessions;
           }

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

           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 * * * *".

       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.

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

       auto_run

       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 "at".

       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.

           MyApp->schedule(
               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 job.

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

   MANUAL EVENTS
       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 "at".

           __PACKAGE__->schedule(
               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.

           http://www.myapp.com/?schedule_trigger=send_email

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

SCHEDULING USING A YAML FILE

       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
       "scheduler.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

SECURITY

       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.

PLUGIN SUPPORT

       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;
               $c->maybe::next::method(@_);

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

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 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.

PERFORMANCE

       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.

METHODS

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

   scheduler_state
       The current state of all scheduled events is available in an easy-to-use format by calling
       $c->scheduler_state.  You can use this data to build an admin view into the scheduling
       engine, for example.  This same data is also displayed on the Catalyst debug screen.

       This method returns an array reference containing a hash reference for each event.

           [
               {
                   'last_run'    => '2005-12-29 16:29:33 EST',
                   'auto_run'    => 1,
                   'last_output' => 1,
                   'at'          => '0 0 * * *',
                   'next_run'    => '2005-12-30 00:00:00 EST',
                   'event'       => '/cron/session_cleanup'
               },
               {
                   'auto_run'    => 1,
                   'at'          => '0 0 * * *',
                   'next_run'    => '2005-12-30 00:00:00 EST',
                   'event'       => '/cron/build_rss'
               },
           ]

INTERNAL METHODS

       The following methods are extended by this plugin.

       dispatch
           The main scheduling logic takes place during the dispatch phase.

       dump_these
           On the Catalyst debug screen, all scheduled events are displayed along with the next
           time they will be executed.

       setup

SEE ALSO

       crontab(5)

AUTHOR

       Andy Grundman, <andy@hybridized.org>

COPYRIGHT

       This program is free software, you can redistribute it and/or modify it under the same
       terms as Perl itself.