README
1 Schedule::Cron
2 ==============
3
4This module provides a simple but complete cron like scheduler. I.e
5this modules can be used for periodically executing Perl subroutines.
6The dates and parameters for the subroutines to be called are
7specified with a format known as crontab entry (see manpage crontab(5)
8or documentation of Schedule::Cron).
9
10The philosophy behind Schedule::Cron is to call subroutines
11periodically from within one single Perl program instead of letting
12cron trigger several (possibly different) Perl scripts. Everything
13under one roof. Furthermore Schedule::Cron provides mechanism to
14create crontab entries dynamically, which isn't that easy with cron.
15
16Schedule::Cron knows about all extensions (well, at least all
17extensions I'm aware of, i.e those of the so called "Vixie" cron) for
18crontab entries like ranges including 'steps', specification of month
19and days of the week by name or coexistence of lists and ranges in the
20same field. And even a bit more (like lists and ranges with symbolic
21names).
22
23This module is rather effective concerning system load. It calculates
24the execution dates in advance and will sleep until those dates are
25reached (and wont wake up every minute to check for execution like
26cron). However, it relies on the accuracy of your sleep() system
27call.
28
29EXAMPLES
30--------
31
32 * Minimalistic:
33
34 use Schedule::Cron;
35
36 my $dispatcher = sub { print "Time to start...\n"};
37 my $cron = new Schedule::Cron($dispatcher);
38
39 $cron->add_entry("0 7 * * *");
40 $cron->run; # Runs forever...
41
42 * A bit more complex:
43
44 use Schedule::Cron;
45
46 my $cron = new Schedule::Cron( sub { print "@_","\n" },
47 file => "check_links.sched",
48 eval => 1);
49
50 sub check_links {
51 my $args = shift;
52 print "URL: ",$args->{url},"\n";
53 print "Depth: ",$args->{depth},"\n";
54 }
55
56 $cron->add_entry("0-40/5,55 3,22 * Jan-Nov Fri",
57 { sub => \&check_links,
58 args => [ { url => "http://www.consol.de",
59 depth => 2 } ],
60 eval => 0 });
61 # ... add more ....
62 $cron->run(detach=>1,pid_file=>"/var/run/checker.pid");
63 # ... continue ...
64
65 * simple cron replacement (for a single crontab file):
66
67 use Schedule::Cron;
68 my $cron = new Schedule::Cron(sub { system(shift) },
69 file => "/var/spool/crontab.perl");
70 $cron->run();
71
72PREREQUISITES
73-------------
74
75In order to install and use this package you will need Perl version
765.005 or better. Furthermore you need the module Time::ParseDate
77(contained in the Time-modules-xx.xxxxx) available on CPAN.
78
79You need a fork()-aware Perl for dispatching the cron jobs. This might
80change in the future. On systems without a fork() system call you can
81use the 'nofork' option to run your jobs within the current process.
82
83OS-DEPENDENCIES
84---------------
85
86Schedule::Cron was tested on a Redhat Linux-Box, but it should work on
87any UNIX Box. In depends on some original UNIX system calls for
88starting jobs and detaching itself to the background:
89
90 * It uses fork() for starting jobs
91 * For detaching it uses either setsid (POSIX) or the ioctl call
92 TIOCNOTTY
93
94The roadmap include plans for porting the fork mechanism over to a
95thread based scheme, which should make dynamic update much easier.
96
97If the system calls mentioned above are not available (which should
98hapen nowadays only under rare circumstances), you can still use the
99'nofork' option to run all jobs within a single process/thread. Please
100refer to the documentation for further reading.
101
102INSTALLATION
103------------
104
105Installation can be don either in the old fashioned way
106
107 perl Makefile.PL
108 make
109 make test
110 make install
111
112or alternatively with Module::Build
113
114 perl Build.PL
115 ./Build
116 ./Build test
117 ./Build install
118
119See the documentation for Schedule::Cron for a detailed description
120and further usage examples.
121
122REPORTING BUGS
123--------------
124
125If you meet a bug (say hello to it ;-), open a ticket at
126https://rt.cpan.org/Ticket/Create.html?Queue=Schedule-Cron.
127
128In addition of a problem description, please add a short description
129of you OS, your Perl version and the version of Time::ParseDate you
130are using. If some of the provided tests fail, include the output of
131'make test TEST_VERBOSE=1' as well.
132
133If you suspect, that the date calculation of the next execution time
134is buggy, please use the following interactive command to generate a
135bug report.
136
137 perl -MSchedule::Cron -e 'bug Schedule::Cron'
138
139You will be asked for a reference time (default: the current time), a
140crontab date pattern (with five columns) and the expected next
141execution date (relative to the reference time). The dates can be
142specified in a format understood by 'parsedate' from Time::ParseDate
143(like 'now + 5 days'). Please include the output of this command.
144
145LICENSE
146-------
147
148Copyright 1999-2011 Roland Huss.
149
150This library is free software; you can redistribute it and/or modify
151it under the same terms as Perl itself.
152
153Enjoy it...
154 ...roland (roland@cpan.org)
155
156