NAME

AnyEvent::DateTime::Cron - AnyEvent crontab with DateTime::Event::Cron

SYNOPSIS

AnyEvent::DateTime::Cron->new()
    ->add(
        '* * * * *'   => sub { warn "Every minute"},
        '*/2 * * * *' => sub { warn "Every second minute"},
      )
    ->start
    ->recv

$cron = AnyEvent::DateTime::Cron->new();
$cron->debug(1)->add(
    {
        cron => '* * * * *',
        cb   => sub {'foo'},
        name => 'job_name_for_debugging'
    },
    {...}.
);

$cron->delete($job_id,$job_id...)

$cv = $cron->start;
$cv->recv;

DESCRIPTION

AnyEvent::DateTime::Cron is an AnyEvent based crontab, which supports all crontab formats recognised by DateTime::Event::Cron.

It allows you to shut down a running instance gracefully, by waiting for any running cron jobs to finish before exiting.

METHODS

new()

$cron = AnyEvent::DateTime::Cron->new();

Creates a new AnyEvent::DateTime::Cron instance - takes no parameters.

add()

$cron->add(
    '* * * * *'     => sub {...},
    {
        cron => '* * * * *',
        cb   => sub {...},
        name => 'my_job'
    }
);

Use add() to add new cron jobs. It accepts a list of crontab entries and callbacks, or alternatively, a list of hashrefs with named parameters. The latter allows you to pass in an optional name parameter, which can be useful for debugging.

Each new job is assigned an ID.

New jobs can be added before running, or while running.

See "CALLBACKS" for more.

delete()

$cron->delete($job_id,$job_id,....)

Delete one or more existing jobs, before starting or while running.

start()

my $cv = $cron->start;
$cv->recv;

Schedules all jobs to start at the next scheduled time, and returns an AnyEvent condvar.

The cron loop can be started by calling recv() on the condvar.

stop()

$cron->stop()

Used to shutdown the cron loop gracefully. You can also shutdown the cron loop by sending a HUP signal to the process.

jobs()

$job = $cron->jobs

Returns a hashref containing all the current cron jobs.

debug()

$cron->debug(1|0)

Turn on debugging.

CALLBACKS

A callback is a coderef (eg an anonymous subroutine) which will be called every time your job is triggered. Callbacks should use AnyEvent themselves, so that they run asynchronously, otherwise they can block the execution of the cron loop, delaying other jobs.

Two parameters are passed to your callback: the main $cv of the cron loop, and the $job_description which contains various details about the current job.

The $cv is the most important parameter, as it allows you to control how your cron loop will shut down. If your callback doesn't use AnyEvent and is blocking, then your callback will complete before it returns to the cron loop.

However, if your callback is running asynchronously (and it really should), then you can block the cron loop from responding to a "stop()" request until your job has completed:

sub {
    my $cv = shift;
    $cv->begin;
    do_something_asynchronous( cb => sub { $cv->end })
}

Callbacks are called inside an eval so if they throw an error, they will warn, but won't cause the cron loop to exit.

AUTHOR

Clinton Gormley, <drtech at cpan.org>

BUGS

If you have any suggestions for improvements, or find any bugs, please report them to http://github.com/clintongormley/AnyEvent-DateTime-Cron/issues. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc AnyEvent::DateTime::Cron

You can also look for information at http://github.com/clintongormley/AnyEvent-DateTime-Cron

LICENSE AND COPYRIGHT

Copyright 2011 Clinton Gormley.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.