view release on metacpan or  search on metacpan

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

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 while providing
the ability to re-run it manually at any time in the future.

B<Signal handling>: The module installs C<$SIG{INT}> and C<$SIG{TERM}>
handlers at load time to ensure shared memory segments are cleaned up when the
host process is killed by a signal. The handlers stop any running event
children, remove all shared memory segments, then re-raise the signal with the
default handler so the process exits with the correct status. If you install
your own handlers for these signals, call C<Async::Event::Interval::_end(1)>
from them before exiting to avoid leaking segments.

The module also sets C<$SIG{CHLD} = 'IGNORE'> at load time to automatically
reap forked event children, preventing zombie processes. If you need to
manage child processes manually (e.g. to call C<waitpid> yourself), install
your own C<$SIG{CHLD}> handler after C<use Async::Event::Interval>.

=head1 METHODS - EVENT OPERATION

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

Returns a new C<Async::Event::Interval> object. Does not start the event. Use
L<start()|/start(@params)> 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.

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

B<Note>: You can set a per-callback-execution timeout via
L<timeout()|/timeout($seconds)> before calling C<start()> to have the event
terminate itself if a callback runs longer than the specified number of seconds.

B<Note>: You can set L<immediate()|/immediate($value)> to have the callback fire
immediately on C<start()>, rather than waiting for the first interval.

=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.

Sets a cooperative C<_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 C<SIGTERM> and polls for up to
C<STOP_TERM_TIMEOUT> seconds, then sends C<SIGKILL> and polls for up to
C<STOP_KILL_TIMEOUT> seconds. Croaks if the process survives both signals.

=head2 restart

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

=head2 status

Returns the event's process ID (true) if it is running, C<0> (false) if it
isn't.

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

=head2 wait($interval)

Blocks until L<waiting()|/waiting> returns true, polling at the given
interval. Useful for one-shot events where you want to wait for the callback
to finish without writing the poll loop by hand.

Parameters:

    $interval

Optional, Number: Polling interval in seconds (integer or float). Defaults to
C<0.01>.

Return: Nothing.

B<Note>: C<wait()> returns once the event is dormant for any reason, including
crash. inspect L</error> and/or L</error_message> if you need to distinguish a
clean finish from a crash.

=head2 waiting