[catagits/Catalyst-Plugin-Scheduler.git] / README

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.
Commit	Line	Data
8cefc921	1	NAME
	2	Catalyst::Plugin::Scheduler - Schedule events to run in a cron-like
	3	fashion
	4
	5	SYNOPSIS
	6	use Catalyst qw/Scheduler/;
	7
	8	# run remove_sessions in the Cron controller every hour
	9	__PACKAGE__->schedule(
	10	at => '0 * * * *',
	11	event => '/cron/remove_sessions'
	12	);
	13
	14	# Run a subroutine at 4:05am every Sunday
	15	__PACKAGE__->schedule(
	16	at => '5 4 * * sun',
	17	event => \&do_stuff,
	18	);
	19
	20	# A long-running scheduled event that must be triggered
	21	# manually by an authorized user
	22	__PACKAGE__->schedule(
	23	trigger => 'rebuild_search_index',
	24	event => '/cron/rebuild_search_index',
	25	);
	26	$ wget -q http://www.myapp.com/?schedule_trigger=rebuild_search_index
	27
	28	DESCRIPTION
	29	This plugin allows you to schedule events to run at recurring intervals.
	30	Events will run during the first request which meets or exceeds the
	31	specified time. Depending on the level of traffic to the application,
	32	events may or may not run at exactly the correct time, but it should be
	33	enough to satisfy many basic scheduling needs.
	34
	35	CONFIGURATION
	36	Configuration is optional and is specified in
	37	MyApp->config->{scheduler}.
	38
	39	logging
	40	Set to 1 to enable logging of events as they are executed. This option
	41	is enabled by default when running under -Debug mode. Errors are always
	42	logged regardless of the value of this option.
	43
	44	time_zone
	45	The time zone of your system. This will be autodetected where possible,
	46	or will default to UTC (GMT). You can override the detection by
	47	providing a valid DateTime time zone string, such as 'America/New_York'.
	48
	49	state_file
	50	The current state of every event is stored in a file. By default this is
	51	$APP_HOME/scheduler.state. This file is created on the first request if
	52	it does not already exist.
	53
	54	yaml_file
	55	The location of the optional YAML event configuration file. By default
	56	this is $APP_HOME/scheduler.yml.
	57
	58	hosts_allow
	59	This option specifies IP addresses for trusted users. This option
	60	defaults to 127.0.0.1. Multiple addresses can be specified by using an
	61	array reference. This option is used for both events where auto_run is
	62	set to 0 and for manually-triggered events.
	63
	64	__PACKAGE__->config->{scheduler}->{hosts_allow} = '192.168.1.1';
65	__PACKAGE__->config->{scheduler}->{hosts_allow} = [
66	'127.0.0.1',
67	'192.168.1.1'
68	];
69
70	SCHEDULING
71	AUTOMATED EVENTS
72	Events are scheduled by calling the class method "schedule".
73
74	MyApp->schedule(
75	at => '0 * * * *',
76	event => '/cron/remove_sessions',
77	);
78
79	package MyApp::Controller::Cron;
80
81	sub remove_sessions : Private {
82	my ( $self, $c ) = @_;
83
84	$c->delete_expired_sessions;
85	}
86
87	at
88	The time to run an event is specified using crontab(5)-style syntax.
89
90	5 0 * * * # 5 minutes after midnight, every day
91	15 14 1 * * # run at 2:15pm on the first of every month
92	0 22 * * 1-5 # run at 10 pm on weekdays
93	5 4 * * sun # run at 4:05am every Sunday
94
95	From crontab(5):
96
97	field allowed values
98	----- --------------
99	minute 0-59
100	hour 0-23
101	day of month 1-31
102	month 0-12 (or names, see below)
103	day of week 0-7 (0 or 7 is Sun, or use names)
104
105	Instead of the first five fields, one of seven special strings may
106	appear:
107
108	string meaning
109	------ -------
110	@yearly Run once a year, "0 0 1 1 *".
111	@annually (same as @yearly)
112	@monthly Run once a month, "0 0 1 * *".
113	@weekly Run once a week, "0 0 * * 0".
114	@daily Run once a day, "0 0 * * *".
115	@midnight (same as @daily)
116	@hourly Run once an hour, "0 * * * *".
117
118	event
119	The event to run at the specified time can be either a Catalyst private
120	action path or a coderef. Both types of event methods will receive the
121	$c object from the current request, but you must not rely on any
122	request-specific information present in $c as it will be from a random
123	user request at or near the event's specified run time.
124
125	Important: Methods used for events should be marked "Private" so that
126	they can not be executed via the browser.
127
128	auto_run
129	The auto_run parameter specifies when the event is allowed to be
130	executed. By default this option is set to 1, so the event will be
131	executed during the first request that matches the specified time in
132	"at".
133
134	If set to 0, the event will only run when a request is made by a user
135	from an authorized address. The purpose of this option is to allow
136	long-running tasks to execute only for certain users.
137
138	MyApp->schedule(
139	at => '0 0 * * *',
140	event => '/cron/rebuild_search_index',
141	auto_run => 0,
142	);
143
144	package MyApp::Controller::Cron;
145
146	sub rebuild_search_index : Private {
147	my ( $self, $c ) = @_;
148
149	# rebuild the search index, this may take a long time
150	}
151
152	Now, the search index will only be rebuilt when a request is made from a
153	user whose IP address matches the list in the "hosts_allow" config
154	option. To run this event, you probably want to ping the app from a cron
155	job.
156
157	0 0 * * * wget -q http://www.myapp.com/
158
159	MANUAL EVENTS
160	To create an event that does not run on a set schedule and must be
161	manually triggered, you can specify the "trigger" option instead of
162	"at".
163
164	__PACKAGE__->schedule(
165	trigger => 'send_email',
166	event => '/events/send_email',
167	);
168
169	The event may then be triggered by a standard web request from an
170	authorized user. The trigger to run is specified by using a special GET
171	parameter, 'schedule_trigger'; the path requested does not matter.
172
173	http://www.myapp.com/?schedule_trigger=send_email
174
175	By default, manual events may only be triggered by requests made from
176	localhost (127.0.0.1). To allow other addresses to run events, use the
177	configuration option "hosts_allow".
178
179	SCHEDULING USING A YAML FILE
180	As an alternative to using the schedule() method, you may define
181	scheduled events in an external YAML file. By default, the plugin looks
182	for the existence of a file called "schedule.yml" in your application's
183	home directory. You can change the filename using the configuration
184	option "yaml_file".
185
186	Modifications to this file will be re-read once per minute during the
187	normal event checking process.
188
189	Here's an example YAML configuration file with 4 events. Each event is
190	denoted with a '-' character, followed by the same parameters used by
191	the "schedule" method. Note that coderef events are not supported by the
192	YAML file.
193
194	---
195	- at: '* * * * *'
196	event: /cron/delete_sessions
197	- event: /cron/send_email
198	trigger: send_email
199	- at: '@hourly'
200	event: /cron/hourly
201	- at: 0 0 * * *
202	auto_run: 0
203	event: /cron/rebuild_search_index
204
205	SECURITY
206	All events are run inside of an eval container. This protects the user
207	from receiving any error messages or page crashes if an event fails to
208	run properly. All event errors are logged, even if logging is disabled.
209
210	PLUGIN SUPPORT
211	Other plugins may register scheduled events if they need to perform
212	periodic maintenance. Plugin authors, be sure to inform your users if
213	you do this! Events should be registered from a plugin's "setup" method.
214
215	sub setup {
216	my $c = shift;
217	$c->NEXT::setup(@_);
218
219	if ( $c->can('schedule') ) {
220	$c->schedule(
221	at => '0 * * * *',
222	event => \&cleanup,
223	);
224	}
225	}
226
227	CAVEATS
228	The time at which an event will run is determined completely by the
229	requests made to the application. Apps with heavy traffic may have
230	events run at very close to the correct time, whereas apps with low
231	levels of traffic may see events running much later than scheduled. If
232	this is a problem, you can use a real cron entry that simply hits your
233	application at the desired time.
234
235	0 * * * * wget -q http://www.myapp.com/
236
237	Events which consume a lot of time will slow the request processing for
238	the user who triggers the event. For these types of events, you should
239	use auto_run => 0 or manual event triggering.
240
241	PERFORMANCE
242	The plugin only checks once per minute if any events need to be run, so
243	the overhead on each request is minimal. On my test server, the
244	difference between running with Scheduler and without was only around
245	0.02% (0.004 seconds).
246
247	Of course, when a scheduled event runs, performance will depend on
248	what's being run in the event.
249
250	METHODS
251	schedule
252	Schedule is a class method for adding scheduled events. See the
253	"SCHEDULING"" in " section for more information.
254
255	scheduler_state
256	The current state of all scheduled events is available in an easy-to-use
257	format by calling $c->scheduler_state. You can use this data to build an
258	admin view into the scheduling engine, for example. This same data is
259	also displayed on the Catalyst debug screen.
260
261	This method returns an array reference containing a hash reference for
262	each event.
263
264	[
265	{
266	'last_run' => '2005-12-29 16:29:33 EST',
267	'auto_run' => 1,
268	'last_output' => 1,
269	'at' => '0 0 * * *',
270	'next_run' => '2005-12-30 00:00:00 EST',
271	'event' => '/cron/session_cleanup'
272	},
273	{
274	'auto_run' => 1,
275	'at' => '0 0 * * *',
276	'next_run' => '2005-12-30 00:00:00 EST',
277	'event' => '/cron/build_rss'
278	},
279	]
280
281	INTERNAL METHODS
282	The following methods are extended by this plugin.
283
284	dispatch
285	The main scheduling logic takes place during the dispatch phase.
286
287	dump_these
288	On the Catalyst debug screen, all scheduled events are displayed
289	along with the next time they will be executed.
290
291	setup
292
293	SEE ALSO
294	crontab(5)
295
296	AUTHOR
297	Andy Grundman, <andy@hybridized.org>
298
299	COPYRIGHT
300	This program is free software, you can redistribute it and/or modify it
301	under the same terms as Perl itself.
302