README

			    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. This might
change in the future. On systems without a fork() system call 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. In depends on some original 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

If the system calls mentioned above are not available (which should
hapen nowadays only under rare circumstances), you can still use the
'nofork' option to run all jobs within a single process/thread. Please
refer to the documentation for further reading.

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

Installation can be done the old fashioned way

   perl Makefile.PL
   make
   make test
   make install

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

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

If you meet a bug (say hello to it ;-), open a ticket at
https://rt.cpan.org/Ticket/Create.html?Queue=Schedule-Cron.          

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.

REPOSITORY
----------

Schedule::Cron's source is located at
https://github.com/rhuss/schedule-cron Please feel free to send me
pull requests if they apply to the license below. Also, don't forget
documentation and tests.

Please note also, that the active development for this module has been
stopped since it is considered  to be feature complete. Bugs and minor
(external) additions will be added from time to time, though.

COPYRIGHT AND LICENSE
---------------------

Copyright (c) 1999-2013 Roland Huß.

Copyright (c) 2022-2023 Nicholas Hubbard.

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

Enjoy it...
                                            ...roland (roland@cpan.org)