NAME

    Async::Event::Interval - Extremely simple timed asynchronous events

SYNOPSIS

    A simple event. Multiple events can be simultaneously used. For an
    example using an event that can share data with the main application,
    examples of how to handle event crashes, and how to send parameters to
    your event callback, see "EXAMPLES".

        use Async::Event::Interval;
    
        my $event = Async::Event::Interval->new(
            1.5, 
            \&callback
        );
    
        $event->start;
    
        for (1..10){
            print "$_: in main loop\n";
    
            $event->stop if $_ == 3;
            $event->start if $_ == 7;
    
            if ($event->status){
                print "event is running\n";
            }
    
            if ($event->status == -1){
                print "event has crashed... restarting it\n";
                $event->restart;
            }
    
            sleep 1;
        }
    
        sub callback {
            print "timed event callback\n";
        }

DESCRIPTION

    Very basic implementation of asynchronous events that are triggered by
    a timed interval.

    Variables are not shared between the main application and the event. To
    do that, you'll need to use some form of memory sharing, such as
    IPC::Shareable. See "EXAMPLES" for an example. At this time, there is
    no real parameter passing or ability to return values. As I said...
    basic.

    Each event is simply a separate forked process, which runs in a while
    loop.

METHODS

 new($delay, $callback)

    Returns a new Async::Event::Interval object. Does not create the event.
    Use start for that.

    Parameters:

        $delay

    Mandatory: The interval on which to trigger your event callback, in
    seconds. Represent partial seconds as a floating point number.

        $callback

    Mandatory: A reference to a subroutine that will be called every time
    the interval expires.

 start

    Starts the event timer. Each time the interval is reached, the event
    callback is executed.

 stop

    Stops the event from being executed.

 restart

    Alias for start(). Re-starts a stop()ped event.

 status

    Returns the event's process ID (true) if it is running, 0 (false) if it
    isn't, and -1 if the event has crashed.

EXAMPLES

 Event Parameters

    You can send in a list of parameters to the event callback. Changing
    these within the main program will have no effect on the values sent
    into the event itself.

        use Async::Event::Interval
    
        my @params = qw(1 2 3);
    
        my $event = Async::Event::Interval->new(
            1,
            \&callback,
            @params
        );
    
        sub callback {
            my ($one, $two, $three) = @_;
            print "$one, $two, $three\n";
        }

 Shared Data

    A timed event where the event callback shares a hash reference with the
    main program.

        use Async::Event::Interval;
        use IPC::Shareable;
    
        my $href = {a => 0, b => 1};
        tie $href, 'IPC::Shareable', undef;
    
        my $event
            = Async::Event::Interval->new(10, \&callback);
    
        sub callback {
            $h->{a}++;
        }

 Event crash: Restart event

        use warnings;
        use strict;
        use feature 'say';
    
        use Async::Event::Interval;
    
        my $event = Async::Event::Interval->new(
            2,
            sub {
                kill 9, $$;
            },
        );
    
        $event->start;
    
        sleep 1; # do stuff
    
        if ($event->status == -1){
            say "event crashed, restarting";
            $event->restart;
        }

 Event crash: End program

        use warnings;
        use strict;
        use feature 'say';
    
        use Async::Event::Interval;
    
        my $event = Async::Event::Interval->new(
            2,
            sub {
                kill 9, $$;
            },
        );
    
        $event->start;
    
        sleep 1; # do stuff
    
        if ($event->status == -1){
            say "event crashed, can't continue...";
            exit;
        }

AUTHOR

    Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

    Copyright 2017 Steve Bertrand.

    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.