view release on metacpan or  search on metacpan

lib/IPC/Run/Timer.pm  view on Meta::CPAN

   1:90        2 minutes, 30 seconds
   1:2:3:4.5   1 day, 2 hours, 3 minutes, 4.5 seconds
   'inf'       the infinity perl special number (the timer never finishes)

Absolute date/time strings are *not* accepted: year, month and
day-of-month parsing is not available (patches welcome :-).

=head2 Interval fudging

When calculating an end time from a start time and an interval, IPC::Run::Timer
instances add a little fudge factor.  This is to ensure that no time will
expire before the interval is up.

First a little background.  Time is sampled in discrete increments.  We'll
call the
exact moment that the reported time increments from one interval to the
next a tick, and the interval between ticks as the time period.  Here's
a diagram of three ticks and the periods between them:


    -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
    ^                   ^                   ^
    |<--- period 0 ---->|<--- period 1 ---->|
    |                   |                   |
  tick 0              tick 1              tick 2

To see why the fudge factor is necessary, consider what would happen
when a timer with an interval of 1 second is started right at the end of
period 0:


    -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
    ^                ^  ^                   ^
    |                |  |                   |
    |                |  |                   |
  tick 0             |tick 1              tick 2
                     |
                 start $t

Assuming that check() is called many times per period, then the timer
is likely to expire just after tick 1, since the time reported will have
lept from the value '0' to the value '1':

    -0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...
    ^                ^  ^   ^               ^
    |                |  |   |               |
    |                |  |   |               |
  tick 0             |tick 1|             tick 2
                     |      |
                 start $t   |
		            |
			check $t

Adding a fudge of '1' in this example means that the timer is guaranteed
not to expire before tick 2.

The fudge is not added to an interval of '0'.

This means that intervals guarantee a minimum interval.  Given that
the process running perl may be suspended for some period of time, or that
it gets busy doing something time-consuming, there are no other guarantees on
how long it will take a timer to expire.

=head1 SUBCLASSING

INCOMPATIBLE CHANGE: Due to the awkwardness introduced by ripping
pseudohashes out of Perl, this class I<no longer> uses the fields
pragma.

=head1 FUNCTIONS & METHODS

=over

=cut

use strict;
use warnings;
use Carp;
use Fcntl;
use Symbol;
use Exporter;
use Scalar::Util ();
use vars qw( $VERSION @ISA @EXPORT_OK %EXPORT_TAGS );

BEGIN {
    $VERSION   = '20260402.0';
    @ISA       = qw( Exporter );
    @EXPORT_OK = qw(
      check
      end_time
      exception
      expire
      interval
      is_expired
      is_reset
      is_running
      name
      reset
      start
      timeout
      timer
    );

    %EXPORT_TAGS = ( 'all' => \@EXPORT_OK );
}

require IPC::Run;
use IPC::Run::Debug;

##
## Some helpers
##
my $resolution = 1;

sub _parse_time {
    for ( $_[0] ) {
        my $val;
        if ( not defined $_ ) {
            $val = $_;
        }
        else {