view release on metacpan or  search on metacpan

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

        $event->restart;
    }

=head2 Event crash: End program

    use warnings;
    use strict;

    use Async::Event::Interval;

    # kill 9, $$ is a contrived self-kill to demonstrate crash detection

    my $event = Async::Event::Interval->new(0.5, sub { kill 9, $$; });

    $event->start;

    sleep 1; # Do stuff

    die "Event crashed, can't continue" if $event->error;

=head2 Immediate first execution

Set C<immediate> to have the callback fire right away on C<start()>, then repeat
at the regular interval thereafter:

    use Async::Event::Interval;

    my $event = Async::Event::Interval->new(5, sub { print "hey\n"; });
    $event->immediate(1);
    $event->start;

    # Callback executed immediately, doesn't wait for the first 5 second
    # interval

    sleep 10;
    $event->stop;

=head2 Event suicidal timeout

Built in is the ability to have the event C<die()> if your callback breaches a
timeout threshold. A timeout is set with L<timeout()|/timeout($seconds)>. It can
be set at any time; it will be picked up on each iteration of your callback.

    use Async::Event::Interval;

    my $event = Async::Event::Interval->new(60, sub { sleep 9; });
    $event->timeout(8);

    $event->start;

    while (1) {
        if ($event->error_message =~ /Callback timed out/) {
            print "Event callback timed out... exiting to troubleshoot\n";
            exit;
        }
    }

=head2 Shared scalar

L<shared_scalar()|/shared_scalar> returns a tied scalar reference whose value
lives in shared memory and is visible to the parent and to event callbacks.
The sub-sections below show common usage patterns; see
L<shared_scalar()|/shared_scalar> for the API reference and constraints.

=head3 Storing simple types

A shared scalar can hold any JSON-representable value: scalars, arrayrefs,
hashrefs, or combinations thereof.

    use Async::Event::Interval;

    my $event = Async::Event::Interval->new(0, sub {});

    my $s     = $event->shared_scalar;

    $$s = 42;
    $$s = 'hello';
    $$s = [1, 2, 3];
    $$s = { lang => 'Perl' };

    print "$$s->{lang}\n";

=head3 Event writes, parent reads

An event populates the scalar in the background; the parent reads it after
the callback finishes.

    use Async::Event::Interval;

    my $s;

    my $event = Async::Event::Interval->new(0, sub {
        $$s = { name => 'alice', score => 42 };
    });

    $s = $event->shared_scalar;

    $event->start;
    $event->wait;

    print "$$s->{name}: $$s->{score}\n";

=head3 Updating a stored hashref

When extending a hashref already in the scalar, mutate through the
dereference directly. The spread idiom also works on modern
C<IPC::Shareable> stacks but is less portable across forked writers on
older versions:

    $$s = { a => 1, b => 2 };

    # Recommended: direct dereferenced mutation
    $$s->{c} = 3;

    # Also works (modern stacks): spread + reassign
    $$s = { %{$$s}, d => 4 };

B<Do not> fetch the reference into a lexical, mutate it, and store it back
(C<< my $h = $$s; $h->{x} = 1; $$s = $h; >>) - that pattern corrupts the
segment. See L<shared_scalar()|/shared_scalar> for the full rules.