+++ /dev/null
-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 "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
-
-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->NEXT::setup(@_);
-
- 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.
-