Schedule::Cron
			    ==============

This module provides  a simple but complete cron  like scheduler.  I.e
this modules can be  used for periodically executing Perl subroutines.
The  dates  and  parameters  for  the subroutines  to  be  called  are
specified with a format known as crontab entry (see manpage crontab(5)
or documentation of Schedule::Cron).

The   philosophy  behind   Schedule::Cron  is   to   call  subroutines
periodically from  within one single  Perl program instead  of letting
cron  trigger several  (possibly different)  Perl  scripts. Everything
under  one  roof.  Furthermore  Schedule::Cron  provides mechanism  to
create crontab entries dynamically, which isn't that easy with cron.

Schedule::Cron  knows  about  all   extensions  (well,  at  least  all
extensions I'm aware of, i.e those  of the so called "Vixie" cron) for
crontab entries like ranges  including 'steps', specification of month
and days of the week by name or coexistence of lists and ranges in the
same field. And  even a bit more (like lists  and ranges with symbolic
names).

This module is rather effective concerning system load.  It calculates
the execution  dates in advance and  will sleep until  those dates are
reached (and  wont wake  up every minute  to check for  execution like
cron).   However, it  relies on  the accuracy  of your  sleep() system
call.

EXAMPLES
--------

 * Minimalistic:

      use Schedule::Cron;

      my $dispatcher = sub { print "Time to start...\n"};
      my $cron = new Schedule::Cron($dispatcher);	 

      $cron->add_entry("0 7 * * *");
      $cron->run;             # Runs forever...

 * A bit more complex:

      use Schedule::Cron;

      my $cron = new Schedule::Cron(  sub { print "@_","\n" },
                                      file  => "check_links.sched",
                                      eval  => 1);

      sub check_links { 
        my $args = shift;
        print "URL:   ",$args->{url},"\n";
        print "Depth: ",$args->{depth},"\n";
      } 

      $cron->add_entry("0-40/5,55 3,22 * Jan-Nov Fri",
                       { sub  => \&check_links,
                         args => [ { url   => "http://www.consol.de", 
                                     depth => 2 } ],
                         eval => 0 });
      # ... add more ....
      $cron->run(detach=>1,pid_file=>"/var/run/checker.pid");
      # ... continue ...

 * simple cron replacement (for a single crontab file):
   
      use Schedule::Cron;
      my $cron = new Schedule::Cron(sub { system(shift) },
                                    file => "/var/spool/crontab.perl");
      $cron->run();
      
PREREQUISITES
-------------

In order  to install and use  this package you will  need Perl version
5.005  or better.   Furthermore  you need  the module  Time::ParseDate
(contained in the Time-modules-xx.xxxxx) available on CPAN.

You need a fork()-aware Perl for dispatching the cron jobs. (Honestly,
I don't yet know, whether the  Win32 Port provides this system call. I
dare  that this  is the  case). This  might change  in the  future. On
system without a working fork() you can use the 'nofork' option to run
your jobs within the current process.

OS-DEPENDENCIES
---------------

Schedule::Cron was tested on a Redhat Linux-Box, but it should work on
any UNIX  Box (still  to be  tested). In depends  on some  UNIX system
calls for starting jobs and detaching itself to the background:

  * It uses fork() for starting jobs
  * For  detaching it  uses either  setsid (POSIX)  or the  ioctl call
    TIOCNOTTY

So at  the moment, it probably  won't run on any  'foreign' ports like
the Win32- or MacOs-Port.

These restrictions might be relaxed in the future.

INSTALLATION
------------

As usual:

   perl Makefile.PL
   make
   make test
   make install

See the  documentation for  Schedule::Cron for a  detailed description
and further usage examples.

REPORTING BUGS
--------------

This module  is still in alpha  stage, so I expect  probably some bugs
showing  up. I.e.  the  calculation of  the next  execution time  of a
specific  crontab  entry  might  fail in  some  obscure  circumstances
(though I did what I could to test it thoroughly).

If  you  meet  a bug  (say  hello  to  it  ;-),  please report  it  to
roland@consol.de with  a subject like  "Schedule::Cron Bug-Report". In
addition of a  problem description, please add a  short description of
you OS, your  Perl version and the version  of Time::ParseDate you are
using. If some of the provided tests fail, include the output of 'make
test TEST_VERBOSE=1' as well.

If you suspect,  that the date calculation of  the next execution time
is buggy, please  use the following interactive command  to generate a
bug report.

   perl -MSchedule::Cron -e 'bug Schedule::Cron'

You will be asked for a  reference time (default: the current time), a
crontab  date  pattern  (with  five  columns) and  the  expected  next
execution date  (relative to  the reference time).   The dates  can be
specified in  a format understood by  'parsedate' from Time::ParseDate
(like 'now  + 5  days').  Please include  the output of  this command.

COPYRIGHT
---------

Copyright 1999,2000,2005 Roland Huss.

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

Enjoy it...
							    ...roland
                                                     roland@consol.de