view release on metacpan or  search on metacpan

lib/Async/Event/Interval.pm  view on Meta::CPAN

        srand();
        $key_str .= ('A'..'Z')[rand(26)];
    }

   return $key_str;
}
sub _rand_shm_lock {
    # Used for the 'protected' option in the %events hash creation

    srand();
    return int(rand(1_000_000));
}
sub _runs {
    my ($self, $increment) = @_;
    $events{$self->id}->{runs}++ if defined $increment;
    return $events{$self->id}->{runs};
}
sub _setup {
    my ($self, $interval, $cb, @args) = @_;
    $self->interval($interval);
    $self->_cb($cb);
    $self->_args(\@args);
}
sub _shm_lock {
    return $shared_memory_protect_lock;
}
sub _started {
    my ($self, $started) = @_;
    $self->{started} = $started if defined $started;
    return $self->{started};
}
sub DESTROY {
    if (defined $_[0]) {
        $_[0]->stop if $_[0]->pid;
    }

    # On events with interval of zero, ForkManager runs finish(), which
    # calls our destroy method. We only want to blow away the %events
    # hash if we truly go out of scope

    return if (caller())[0] eq 'Parallel::ForkManager::Child';

    delete $events{$_[0]->id};
}
sub _end {
    if (! keys %events) {
        IPC::Shareable::clean_up_protected(_shm_lock());
    }
}
END {
    _end();
}
sub _vim{}

1;

__END__

=head1 NAME

Async::Event::Interval - Scheduled and one-off asynchronous events

=for html
<a href="https://github.com/stevieb9/async-event-interval/actions"><img src="https://github.com/stevieb9/async-event-interval/workflows/CI/badge.svg"/></a>
<a href='https://coveralls.io/github/stevieb9/async-event-interval?branch=master'><img src='https://coveralls.io/repos/stevieb9/async-event-interval/badge.svg?branch=master&service=github' alt='Coverage Status' /></a>


=head1 SYNOPSIS

A simple event that updates JSON data from a website using a shared scalar
variable, while allowing the main application to continue running in the
foreground. Multiple events can be simultaneously used if desired.

See L</EXAMPLES> for other various functionality of this module.

    use warnings;
    use strict;

    use Async::Event::Interval;

    my $event = Async::Event::Interval->new(2, \&callback);

    my $json = $event->shared_scalar;

    $event->start;

    while (1) {
        print "$$json\n";

        #... do other things

        $event->restart if $event->error;
    }

    sub callback {
        $$json = ...; # Fetch JSON from website
    }

=head1 DESCRIPTION

Very basic implementation of asynchronous events triggered by a timed interval.
If a time of zero is specified, we'll run the event only once.

=head1 METHODS - EVENT OPERATION

=head2 new($delay, $callback, @params)

Returns a new C<Async::Event::Interval> object. Does not create the event. Use
C<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. If zero is specified,
we'll simply run the event once and stop.

    $callback

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

    @params

Optional, List: A list of parameters to pass to the callback. Note that these
are not shared parameters and are a copy only, so changes to them in the main
code will not be seen in the event, and vice-versa. See L</shared_scalar> if
you'd like to use variables that can be shared between the main application and
the events.

Also note: These parameters are sent into the event only once. Each
time the callback is called, they will receive the exact same set of params.

To have the event get different values in the params each time the callback is
called, see L</start(@params)>.

=head2 start(@params)

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

Parameters:

    @params

Optional, List: A list of parameters that the callback will receive each time
the callback is called. This is most effective in single-run mode so you can
send in different parameter values on each incarnation. The parameters can be
any type of any complexity. Your callback will get them in whatever order you
send them in as.

=head2 stop

Stops the event from being executed.

=head2 restart

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

=head2 status