1 package Catalyst::Plugin::Scheduler;
5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
7 use DateTime::Event::Cron;
8 use DateTime::TimeZone;
11 use Storable qw/lock_store lock_retrieve/;
14 our $VERSION = '0.10';
16 __PACKAGE__->mk_classdata( '_events' => [] );
17 __PACKAGE__->mk_accessors('_event_state');
20 my ( $class, %args ) = @_;
22 unless ( $args{event} ) {
23 Catalyst::Exception->throw(
24 message => 'The schedule method requires an event parameter' );
27 my $conf = $class->config->{scheduler};
30 trigger => $args{trigger},
31 event => $args{event},
32 auto_run => ( defined $args{auto_run} ) ? $args{auto_run} : 1,
37 # replace keywords that Set::Crontab doesn't support
38 $args{at} = _prepare_cron( $args{at} );
40 # parse the cron entry into a DateTime::Set
42 eval { $set = DateTime::Event::Cron->from_cron( $args{at} ) };
44 Catalyst::Exception->throw(
45 "Scheduler: Unable to parse 'at' value "
50 $event->{at} = $args{at};
55 push @{ $class->_events }, $event;
61 $c->maybe::next::method();
63 $c->_get_event_state();
67 # check if a minute has passed since our last check
68 # This check is not run if the user is manually triggering an event
69 if ( time - $c->_event_state->{last_check} < 60 ) {
70 return unless $c->req->params->{schedule_trigger};
72 my $last_check = $c->_event_state->{last_check};
73 $c->_event_state->{last_check} = time;
74 $c->_save_event_state();
76 my $conf = $c->config->{scheduler};
77 my $last_check_dt = DateTime->from_epoch(
79 time_zone => $conf->{time_zone}
81 my $now = DateTime->now( time_zone => $conf->{time_zone} );
84 for my $event ( @{ $c->_events } ) {
87 if ( $event->{trigger} && $c->req->params->{schedule_trigger}
88 && $event->{trigger} eq $c->req->params->{schedule_trigger} )
91 # manual trigger, run it now
92 next EVENT unless $c->_event_authorized;
96 next EVENT unless $event->{set};
97 $next_run = $event->{set}->next($last_check_dt);
100 if ( $next_run <= $now ) {
102 # do some security checking for non-auto-run events
103 if ( !$event->{auto_run} ) {
104 next EVENT unless $c->_event_authorized;
107 # make sure we're the only process running this event
108 next EVENT unless $c->_mark_running($event);
110 my $event_name = $event->{trigger} || $event->{event};
111 $c->log->debug("Scheduler: Executing $event_name")
112 if $c->config->{scheduler}->{logging};
115 local $c->{error} = [];
117 # return value/output from the event, if any
123 # do not allow the event to modify the response
124 local $c->res->{body};
125 local $c->res->{cookies};
126 local $c->res->{headers};
127 local $c->res->{location};
128 local $c->res->{status};
130 if ( ref $event->{event} eq 'CODE' ) {
131 $output = $event->{event}->($c);
134 $output = $c->forward( $event->{event} );
137 my @errors = @{ $c->{error} };
138 push @errors, $@ if $@;
141 'Scheduler: Error executing ' . "$event_name: $_" )
143 $output = join '; ', @errors;
146 $c->_mark_finished( $event, $output );
154 # initial configuration
155 $c->config->{scheduler}->{logging} ||= ( $c->debug ) ? 1 : 0;
156 $c->config->{scheduler}->{time_zone} ||= $c->_detect_timezone();
157 $c->config->{scheduler}->{state_file} ||= $c->path_to('scheduler.state');
158 $c->config->{scheduler}->{hosts_allow} ||= '127.0.0.1';
159 $c->config->{scheduler}->{yaml_file} ||= $c->path_to('scheduler.yml');
161 # Always start with a clean state
162 if ( -e $c->config->{scheduler}->{state_file} ) {
164 'Scheduler: Removing old state file ' .
165 $c->config->{scheduler}->{state_file}
166 ) if $c->config->{scheduler}->{logging};
168 unlink $c->config->{scheduler}->{state_file}
169 or Catalyst::Exception->throw(
170 message => 'Scheduler: Unable to remove old state file '
171 . $c->config->{scheduler}->{state_file} . " ($!)"
175 $c->maybe::next::method(@_);
181 return ( $c->maybe::next::method(@_) ) unless @{ $c->_events };
183 # for debugging, we dump out a list of all events with their next
186 $c->maybe::next::method(@_),
187 [ 'Scheduled Events', $c->scheduler_state ],
191 sub scheduler_state {
194 $c->_get_event_state();
196 my $conf = $c->config->{scheduler};
197 my $now = DateTime->now( time_zone => $conf->{time_zone} );
199 my $last_check = $c->_event_state->{last_check};
200 my $last_check_dt = DateTime->from_epoch(
201 epoch => $last_check,
202 time_zone => $conf->{time_zone},
206 for my $event ( @{ $c->_events } ) {
208 for my $key ( qw/at trigger event auto_run/ ) {
209 $dump->{$key} = $event->{$key} if $event->{$key};
212 # display the next run time
213 if ( $event->{set} ) {
214 my $next_run = $event->{set}->next($last_check_dt);
217 . q{ } . $next_run->hms
218 . q{ } . $next_run->time_zone_short_name;
221 # display the last run time
223 = $c->_event_state->{events}->{ $event->{event} }->{last_run};
225 $last_run = DateTime->from_epoch(
227 time_zone => $conf->{time_zone},
231 . q{ } . $last_run->hms
232 . q{ } . $last_run->time_zone_short_name;
235 # display the result of the last run
237 = $c->_event_state->{events}->{ $event->{event} }->{last_output};
239 $dump->{last_output} = $output;
242 push @{$event_dump}, $dump;
248 # check and reload the YAML file with schedule data
252 # each process needs to load the YAML file independently
253 if ( $c->_event_state->{yaml_mtime}->{$$} ||= 0 ) {
254 return if ( time - $c->_event_state->{last_check} < 60 );
257 return unless -e $c->config->{scheduler}->{yaml_file};
260 my $mtime = ( stat $c->config->{scheduler}->{yaml_file} )->mtime;
261 if ( $mtime > $c->_event_state->{yaml_mtime}->{$$} ) {
262 $c->_event_state->{yaml_mtime}->{$$} = $mtime;
264 # clean up old PIDs listed in yaml_mtime
265 foreach my $pid ( keys %{ $c->_event_state->{yaml_mtime} } ) {
266 if ( $c->_event_state->{yaml_mtime}->{$pid} < $mtime ) {
267 delete $c->_event_state->{yaml_mtime}->{$pid};
270 $c->_save_event_state();
272 # wipe out all current events and reload from YAML
275 my $file = $c->config->{scheduler}->{yaml_file};
278 eval { require YAML::Syck; };
281 $yaml = YAML::LoadFile( "$file" );
284 open( my $fh, $file ) or die $!;
285 my $content = do { local $/; <$fh> };
287 $yaml = YAML::Syck::Load( $content );
290 foreach my $event ( @{$yaml} ) {
291 $c->schedule( %{$event} );
294 $c->log->info( "Scheduler: PID $$ loaded "
296 . ' events from YAML file' )
297 if $c->config->{scheduler}->{logging};
301 $c->log->error("Scheduler: Error reading YAML file: $@");
305 # Detect the current time zone
306 sub _detect_timezone {
310 eval { $tz = DateTime::TimeZone->new( name => 'local' ) };
313 'Scheduler: Unable to autodetect local time zone, using UTC')
314 if $c->config->{scheduler}->{logging};
319 'Scheduler: Using autodetected time zone: ' . $tz->name )
320 if $c->config->{scheduler}->{logging};
325 # Check for authorized users on non-auto events
326 sub _event_authorized {
329 # this should never happen, but just in case...
330 return unless $c->req->address;
332 my $hosts_allow = $c->config->{scheduler}->{hosts_allow};
333 $hosts_allow = [$hosts_allow] unless ref($hosts_allow) eq 'ARRAY';
334 my $allowed = Set::Scalar->new( @{$hosts_allow} );
335 return $allowed->contains( $c->req->address );
338 # get the state from the state file
339 sub _get_event_state {
342 if ( -e $c->config->{scheduler}->{state_file} ) {
344 lock_retrieve $c->config->{scheduler}->{state_file} );
348 # initialize the state file
350 { last_check => time,
355 $c->_save_event_state();
359 # Check the state file to ensure we are the only process running an event
361 my ( $c, $event ) = @_;
363 $c->_get_event_state();
366 $c->_event_state->{events}->{ $event->{event} }->{running};
368 # this is a 2-step process to prevent race conditions
369 # 1. write the state file with our PID
370 $c->_event_state->{events}->{ $event->{event} }->{running} = $$;
371 $c->_save_event_state();
373 # 2. re-read the state file and make sure it's got the same PID
374 $c->_get_event_state();
375 if ( $c->_event_state->{events}->{ $event->{event} }->{running} == $$ ) {
382 # Mark an event as finished
384 my ( $c, $event, $output ) = @_;
386 $c->_event_state->{events}->{ $event->{event} }->{running} = 0;
387 $c->_event_state->{events}->{ $event->{event} }->{last_run} = time;
388 $c->_event_state->{events}->{ $event->{event} }->{last_output} = $output;
389 $c->_save_event_state();
392 # update the state file on disk
393 sub _save_event_state {
396 lock_store $c->_event_state, $c->config->{scheduler}->{state_file};
399 # Set::Crontab does not support day names, or '@' shortcuts
403 return $cron unless $cron =~ /\w/;
429 'yearly' => '0 0 1 1 *',
430 'annually' => '0 0 1 1 *',
431 'monthly' => '0 0 1 * *',
432 'weekly' => '0 0 * * 0',
433 'daily' => '0 0 * * *',
434 'midnight' => '0 0 * * *',
435 'hourly' => '0 * * * *',
438 if ( $cron =~ /^\@/ ) {
440 return $replace_at{ $cron };
443 for my $name ( keys %replace ) {
444 my $value = $replace{$name};
445 $cron =~ s/$name/$value/i;
446 last unless $cron =~ /\w/;
458 Catalyst::Plugin::Scheduler - Schedule events to run in a cron-like fashion
462 use Catalyst qw/Scheduler/;
464 # run remove_sessions in the Cron controller every hour
465 __PACKAGE__->schedule(
467 event => '/cron/remove_sessions'
470 # Run a subroutine at 4:05am every Sunday
471 __PACKAGE__->schedule(
476 # A long-running scheduled event that must be triggered
477 # manually by an authorized user
478 __PACKAGE__->schedule(
479 trigger => 'rebuild_search_index',
480 event => '/cron/rebuild_search_index',
482 $ wget -q http://www.myapp.com/?schedule_trigger=rebuild_search_index
486 This plugin allows you to schedule events to run at recurring intervals.
487 Events will run during the first request which meets or exceeds the specified
488 time. Depending on the level of traffic to the application, events may or may
489 not run at exactly the correct time, but it should be enough to satisfy many
490 basic scheduling needs.
494 Configuration is optional and is specified in MyApp->config->{scheduler}.
498 Set to 1 to enable logging of events as they are executed. This option is
499 enabled by default when running under -Debug mode. Errors are always logged
500 regardless of the value of this option.
504 The time zone of your system. This will be autodetected where possible, or
505 will default to UTC (GMT). You can override the detection by providing a
506 valid L<DateTime> time zone string, such as 'America/New_York'.
510 The current state of every event is stored in a file. By default this is
511 $APP_HOME/scheduler.state. This file is created on the first request if it
512 does not already exist.
516 The location of the optional YAML event configuration file. By default this
517 is $APP_HOME/scheduler.yml.
521 This option specifies IP addresses for trusted users. This option defaults
522 to 127.0.0.1. Multiple addresses can be specified by using an array
523 reference. This option is used for both events where auto_run is set to 0
524 and for manually-triggered events.
526 __PACKAGE__->config->{scheduler}->{hosts_allow} = '192.168.1.1';
527 __PACKAGE__->config->{scheduler}->{hosts_allow} = [
534 =head2 AUTOMATED EVENTS
536 Events are scheduled by calling the class method C<schedule>.
540 event => '/cron/remove_sessions',
543 package MyApp::Controller::Cron;
545 sub remove_sessions : Private {
546 my ( $self, $c ) = @_;
548 $c->delete_expired_sessions;
553 The time to run an event is specified using L<crontab(5)>-style syntax.
555 5 0 * * * # 5 minutes after midnight, every day
556 15 14 1 * * # run at 2:15pm on the first of every month
557 0 22 * * 1-5 # run at 10 pm on weekdays
558 5 4 * * sun # run at 4:05am every Sunday
567 month 0-12 (or names, see below)
568 day of week 0-7 (0 or 7 is Sun, or use names)
570 Instead of the first five fields, one of seven special strings may appear:
574 @yearly Run once a year, "0 0 1 1 *".
575 @annually (same as @yearly)
576 @monthly Run once a month, "0 0 1 * *".
577 @weekly Run once a week, "0 0 * * 0".
578 @daily Run once a day, "0 0 * * *".
579 @midnight (same as @daily)
580 @hourly Run once an hour, "0 * * * *".
584 The event to run at the specified time can be either a Catalyst private
585 action path or a coderef. Both types of event methods will receive the $c
586 object from the current request, but you must not rely on any request-specific
587 information present in $c as it will be from a random user request at or near
588 the event's specified run time.
590 Important: Methods used for events should be marked C<Private> so that
591 they can not be executed via the browser.
595 The auto_run parameter specifies when the event is allowed to be executed.
596 By default this option is set to 1, so the event will be executed during the
597 first request that matches the specified time in C<at>.
599 If set to 0, the event will only run when a request is made by a user from
600 an authorized address. The purpose of this option is to allow long-running
601 tasks to execute only for certain users.
605 event => '/cron/rebuild_search_index',
609 package MyApp::Controller::Cron;
611 sub rebuild_search_index : Private {
612 my ( $self, $c ) = @_;
614 # rebuild the search index, this may take a long time
617 Now, the search index will only be rebuilt when a request is made from a user
618 whose IP address matches the list in the C<hosts_allow> config option. To
619 run this event, you probably want to ping the app from a cron job.
621 0 0 * * * wget -q http://www.myapp.com/
625 To create an event that does not run on a set schedule and must be manually
626 triggered, you can specify the C<trigger> option instead of C<at>.
628 __PACKAGE__->schedule(
629 trigger => 'send_email',
630 event => '/events/send_email',
633 The event may then be triggered by a standard web request from an authorized
634 user. The trigger to run is specified by using a special GET parameter,
635 'schedule_trigger'; the path requested does not matter.
637 http://www.myapp.com/?schedule_trigger=send_email
639 By default, manual events may only be triggered by requests made from
640 localhost (127.0.0.1). To allow other addresses to run events, use the
641 configuration option L</hosts_allow>.
643 =head1 SCHEDULING USING A YAML FILE
645 As an alternative to using the schedule() method, you may define scheduled
646 events in an external YAML file. By default, the plugin looks for the
647 existence of a file called C<scheduler.yml> in your application's home
648 directory. You can change the filename using the configuration option
651 Modifications to this file will be re-read once per minute during the normal
652 event checking process.
654 Here's an example YAML configuration file with 4 events. Each event is
655 denoted with a '-' character, followed by the same parameters used by the
656 C<schedule> method. Note that coderef events are not supported by the YAML
661 event: /cron/delete_sessions
662 - event: /cron/send_email
668 event: /cron/rebuild_search_index
672 All events are run inside of an eval container. This protects the user from
673 receiving any error messages or page crashes if an event fails to run
674 properly. All event errors are logged, even if logging is disabled.
676 =head1 PLUGIN SUPPORT
678 Other plugins may register scheduled events if they need to perform periodic
679 maintenance. Plugin authors, B<be sure to inform your users> if you do this!
680 Events should be registered from a plugin's C<setup> method.
684 $c->maybe::next::method(@_);
686 if ( $c->can('schedule') ) {
696 The time at which an event will run is determined completely by the requests
697 made to the application. Apps with heavy traffic may have events run at very
698 close to the correct time, whereas apps with low levels of traffic may see
699 events running much later than scheduled. If this is a problem, you can use
700 a real cron entry that simply hits your application at the desired time.
702 0 * * * * wget -q http://www.myapp.com/
704 Events which consume a lot of time will slow the request processing for the
705 user who triggers the event. For these types of events, you should use
706 auto_run => 0 or manual event triggering.
710 The plugin only checks once per minute if any events need to be run, so the
711 overhead on each request is minimal. On my test server, the difference
712 between running with Scheduler and without was only around 0.02% (0.004
715 Of course, when a scheduled event runs, performance will depend on what's
716 being run in the event.
722 Schedule is a class method for adding scheduled events. See the
723 L<"/SCHEDULING"> section for more information.
725 =head2 scheduler_state
727 The current state of all scheduled events is available in an easy-to-use
728 format by calling $c->scheduler_state. You can use this data to build an
729 admin view into the scheduling engine, for example. This same data is also
730 displayed on the Catalyst debug screen.
732 This method returns an array reference containing a hash reference for each
737 'last_run' => '2005-12-29 16:29:33 EST',
741 'next_run' => '2005-12-30 00:00:00 EST',
742 'event' => '/cron/session_cleanup'
747 'next_run' => '2005-12-30 00:00:00 EST',
748 'event' => '/cron/build_rss'
752 =head1 INTERNAL METHODS
754 The following methods are extended by this plugin.
760 The main scheduling logic takes place during the dispatch phase.
764 On the Catalyst debug screen, all scheduled events are displayed along with
765 the next time they will be executed.
777 Andy Grundman, <andy@hybridized.org>
781 This program is free software, you can redistribute it and/or modify it
782 under the same terms as Perl itself.