NAME

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

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 the "SCENARIOS/EXAMPLES" section for further usage examples.

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 {
    my $content = get_webpage_content();
    $$json = decode_json($content);
}

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.

METHODS - EVENT OPERATION

new($delay, $callback, @params)

Returns a new Async::Event::Interval object. Does not start 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. 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 "shared_scalar" if you'd like to use variables that can be shared between the main application and the events.

Optional: Set a per-callback-execution timeout via "timeout($seconds)" before calling start to have the event terminate itself if a callback runs longer than the specified number of seconds.

Optional: Set immediate to have the callback fire immediately on start, rather than waiting for the first interval. See "immediate($value)".

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 "start(@params)".

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.

stop

Stops the event from being executed. Sets a cooperative _stop_requested flag in shared memory so a well-behaved child exits its event loop on the next iteration. If the child is stuck in a long-running callback, escalates: sends SIGTERM and polls for up to STOP_TERM_TIMEOUT seconds, then sends SIGKILL and polls for up to STOP_KILL_TIMEOUT seconds. Croaks if the process survives both signals.

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.

Side effect: calling status() probes the event's child process with kill 0 to detect a crashed background process. If the process is gone, the event's internal _started flag is cleared, an internal _crashed flag is set, and pid is cleared (so "pid" subsequently returns undef). Subsequent calls to status(), "error", or "waiting" see the updated state. To clear the crash flag, call "start" or "restart".

waiting

Returns true if the event is dormant and is ready for a start() or restart() command. Returns false if the event is already running.

Side effect: calls error() and status() internally, both of which probe the child process (see those methods for details).

error

Returns true if an event crashed unexpectedly in the background, and is ready for a start() or restart() command. Returns false if the event is not in an error state.

Side effect: calling error() runs the same crash probe documented under "status". The event's internal flags and PID may be mutated as a side effect of this call.

See "errors" for the crash count.

interval($seconds)

Gets/sets the delay time (in seconds) between each execution of the event's callback code. You can use this method to change the delay between calls during the event's lifecycle.

Parameters:

$seconds

Optional, Number: The number of seconds (integer or floating point) to delay between executions.

Return: Number (integer or float), the number of seconds between execution runs. If the interval was set to zero, the return will be 0.

timeout($seconds)

Sets (or gets) a per-callback-execution timeout in seconds. If the event's callback takes longer than the specified time to complete, the event will terminate itself with an error.

Set a timeout of 0 or undef to disable it (the default is no timeout).

The timeout is read from shared memory at the start of every callback invocation, so changes made via this setter while an event is running take effect on the next iteration of the interval loop (mirroring "interval($seconds)").

Parameters:

$seconds

Optional, Integer: The number of whole seconds the callback is allowed to execute for before timing out. Must be a non-negative integer; fractional seconds are not supported. Use 0 or undef to disable.

immediate($value)

Sets (or gets) whether the callback fires immediately on start, bypassing the first interval wait. Subsequent invocations follow the normal interval cadence.

Set a value of 1 to enable immediate first execution. Set to 0 or undef to disable (the default).

The flag is read from shared memory on each iteration of the event loop. Changes made before calling start always take effect. Changes made after start take effect on the next loop iteration; however, once the first callback has executed, immediate has already served its purpose and further changes will not trigger another immediate execution. Restart the event for a fresh immediate check.

Parameters:

$value

Optional, Integer: 1 to enable immediate first execution, 0 or undef to disable. Must be a non-negative integer when defined.

shared_scalar

Returns a reference to a scalar variable that can be shared between the main process and the events. This reference can be used within multiple events, and multiple shared scalars can be created by each event.

To read from or assign to the returned scalar, you must dereference it. Eg. $$shared_scalar = 1;.

Lifetime: The underlying shared memory segment is owned by the event object that created it. When the event goes out of scope (and its DESTROY runs), every shared_scalar it created is released. Do not dereference the returned scalar reference after the owning event has been destroyed; the segment will no longer exist. If you need a shared scalar whose lifetime is independent of any event, tie it directly with IPC::Shareable.

Hex keys: "info" and "events" return shared_scalars as an arrayref of hex key strings. These identify the underlying IPC segments and can be used to re-attach from another process:

my $info = $event->info;
for my $key (@{ $info->{shared_scalars} }) {
    tie my $scalar, 'IPC::Shareable', $key, {};
    print "$$scalar\n";
}

In practice, however, it is simpler to retain the reference returned by shared_scalar() and use it directly.

METHODS - EVENT INFORMATION

errors

Returns the number of times a started or restarted event has crashed unexpectedly. See "error" to test whether the event is currently in an error state.

error_message

Returns the error message (if any) that caused the most recent event crash.

If the crash was caused by "timeout($seconds)" firing, the message has the form "timed out after Ns\n" (where N is the timeout in whole seconds), which consumers can pattern-match on to distinguish timeouts from other callback failures.

events

Returns a plain hash reference containing a snapshot of the data for all existing events. The returned hash is a copy; modifying it will not affect the live events. shared_scalars is an arrayref of the hex key strings for each shared scalar created by the event; use the scalar reference returned by "shared_scalar" to read or write values.

The snapshot is taken under a read lock (LOCK_SH) for consistency.

$VAR1 = {
    '0' => {
        'shared_scalars' => [
            '0x4a3f2c1b5d6e',
            '0x7f8e9d0c1b2a'
        ],
        'pid'       => 11859,
        'runs'      => 16,
        'errors'    => 0,
        'interval'  => 5,
    },
    '1' => {
        'pid'           => 11860,
        'runs'          => 447,
        'errors'        => 2,
        'interval'      => 0.6,
        'error_message' => 'File notes.txt not found at scripts/write_file.pl line 227',
    }
};

id

Returns the integer ID of the event.

info

Returns a hash reference containing a snapshot of the event's data. The returned hash is a copy; modifying it will not affect the live event. shared_scalars is an arrayref of hex key strings; use the scalar reference returned by "shared_scalar" to read or write values.

The snapshot is taken under a read lock (LOCK_SH) for consistency.

$VAR1 = {
    'shared_scalars' => [
        '0x4a3f2c1b5d6e',
        '0x7f8e9d0c1b2a'
    ],
    'pid'      => 6841,
    'runs'     => 4077,
    'errors'   => 0,
    'interval' => 1.4,
};

pid

Returns the Process ID the event is running under:

undef before start() has ever been called
undef after a crashed event has been detected (via a call to "error", "status", or "waiting") and until the next start() / restart()
The PID of the most recent child after a clean stop() (a dead process; provided for diagnostic purposes only)
A positive integer (the PID of the currently running child) otherwise

Use "status" and "error" to determine which state applies; do not interpret the integer value beyond "some past or current child PID". Prior versions returned the magic value -99 after a crash; that sentinel has been retired in favor of "error".

runs

Returns the number of executions of the event's callback routine.

SCENARIOS/EXAMPLES

Run once

Send in an interval of zero (0) to have your event run a single time. Call start() repeatedly for numerous individual/one-off runs.

use Async::Event::Interval

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

$event->start;

# Do other work while the event runs...

# waiting() probes the child process; returns true once the
# one-shot has finished, allowing a clean restart
$event->start if $event->waiting;

Change delay interval during operation

Change the delay interval from 5 to 600 seconds after the event has fired 100 times

use Async::Event::Interval

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

$event->start;

while (1) {
    if ($event->runs > 99 && $event->interval != 600) {
        $event->interval(600);
    }

    #... do stuff
}

Event error management

If an event crashes, print out error information and restart the event. If an event crashes five or more times, print the most recent error message and halt the program so you can figure out what's wrong with your callback code.

use Async::Event::Interval

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

$event->start;

while (1) {

    #... do stuff

    if ($event->errors >= 5) {
        print $event->error_message;
        exit;
    }

    if ($event->error) {
        printf(
            "Runs: %d, Runs errored: %d, Last error message: %s\n",
            $event->runs,
            $event->errors,
            $event->error_message;
        );

        $event->restart;
    }
}

Per callback execution parameters

When using an event in a one-off situation where you restart the same event manually, you can send in parameters that differ for each execution.

Send in a list of any data type. The list will be sent as-is to the callback.

NOTE: Parameters sent in to the start() method will override ones sent into the new() method.

For example:

use Async::Event::Interval

my @params = (
    { a => 1 },
    { b => 2 },
    { c => 3 },
);

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

my $count = 0;

for my $href (@params) {
    $event->start($count, $href);
    while (! $event->waiting) {}
    $count++;
}

sub callback {
    my ($count, $href) = @_;
    my ($k, $v) = each %$href;
    print "$count: $k = $v\n";
}

Global event callback parameters

You can send in a list of parameters to the event callback when instantiating the event. Note that these parameters will remain the same for every call of the callback.

Changing these within the main program will have no effect on the values sent into the event itself. These parameter variables are copies and are not shared. For shared variables, see "shared_scalar".

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";
}

Event crash: Restart event

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

if ($event->error){
    print "Event crashed, restarting\n";
    $event->restart;
}

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;

Shared data across events

This software uses IPC::Shareable internally, so it's automatically installed for you already. You can use shared data for use across many processes and events, and if you use the same IPC key, even across multiple scripts.

Here's an example that uses a hash that's stored in shared memory, where the parent process (the script) and two other processes (the two events) all share and update the same hash.

Important: keep shared hash values flat (strings, numbers). Nested data structures (e.g. $hash{$$}{key}) cause IPC::Shareable to create child shared-memory segments whose ownership can conflict across forked processes, leading to data loss. For per-event shared data, consider "shared_scalar" instead.

use Async::Event::Interval;
use IPC::Shareable;

tie my %shared_data, 'IPC::Shareable', {
    key         => '123456789',
    create      => 1,
    destroy     => 1
};

$shared_data{$$}++;

my $event_one = Async::Event::Interval->new(0.2, \&update);
my $event_two = Async::Event::Interval->new(1, \&update);

$event_one->start;
$event_two->start;

sleep 10;

$event_one->stop;
$event_two->stop;

for my $pid (keys %shared_data) {
    printf(
        "Process ID %d executed %d times\n",
        $pid,
        $shared_data{$pid}
    );
}

for my $event ($event_one, $event_two) {
    printf(
        "Event ID %d with PID %d ran %d times, with %d errors and an interval" .
        " of %.2f seconds\n",
        $event->id,
        $event->pid,
        $event->runs,
        $event->errors,
        $event->interval
    );
}

sub update {
    # Because each event runs in its own process, $$ will be set to the
    # process ID of the calling event, even though they both call this
    # same function

    $shared_data{$$}++;
}

Immediate first execution

Set immediate to have the callback fire right away on 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;

sleep 10;
$event->stop;

Closures and lexical variables

When a callback closes over a lexical variable, the child process sees the value that existed at the moment of fork. For one-shot events (interval 0), each start() forks a fresh child, so changes to the lexical between calls are visible:

use Async::Event::Interval;

my $msg = "first run";
my $e = Async::Event::Interval->new(0, sub { print "$msg\n"; });

$e->start;       # prints "first run"
select(undef, undef, undef, 0.3);

$msg = "second run";
$e->start;       # prints "second run"

For interval events (interval > 0), the child is forked once on the first start() and loops. Parent-side changes to closed-over lexicals will never be seen by the already-running child. Use "shared_scalar" or start(@params) for data that must cross process boundaries mid-run.

AUTHOR

Steve Bertrand, <steveb at cpan.org>

LICENSE AND COPYRIGHT

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.

To install Async::Event::Interval, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Async::Event::Interval

CPAN shell

perl -MCPAN -e shell
install Async::Event::Interval

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS - EVENT OPERATION

new($delay, $callback, @params)

start(@params)

stop

restart

status

waiting

error

interval($seconds)

timeout($seconds)

immediate($value)

shared_scalar

METHODS - EVENT INFORMATION

errors

error_message

events

id

info

pid

runs

SCENARIOS/EXAMPLES

Run once

Change delay interval during operation

Event error management

Per callback execution parameters

Global event callback parameters

Event crash: Restart event

Event crash: End program

Shared data across events

Immediate first execution

Closures and lexical variables

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions

Keyboard Shortcuts