for review: Elapse.pm

[Scott R. Godin]

just a bit of silliness I conconcted while reading Damian's OOP... Your 
thoughtful appraisal and suggestions would be most welcome. I'm still 
experimenting with it off and on. :-) 

I've found it most useful when downloading large #'s of files and 
gaugeing(sp?) the speed of my new cablemodem at various times of the 
day. 

Is there a good way to turn a <mailto:[EMAIL PROTECTED]> into a 
proper link in the pod, or is that not part of the functionality? I 
played around a bit but couldn't discover if there was a special trick 
to do so and didn't spend a lot of time searching deeper, figuring it's 
a frivolous option, at this point in the life of the script. :-) 

-=-

package Elapse;
$Elapse::VERSION = 1.12;
require 5.006;
use strict;
use autouse 'Carp' => qw(confess);
use POSIX qw/ strftime /;
use Time::HiRes qw/ gettimeofday /; 

sub TIESCALAR
{
    my( $class, $val ) = @_;
    $val = "" unless defined($val); 
    confess "Elapse->lapse() unable to use referenced values"
      if ref($val); 

    bless { now => [gettimeofday()], val => $val }, $class;
}

sub FETCH
{
    my ( $impl ) = @_;
    my ($time, $ms) =  gettimeofday();
    if ( $ms < $impl->{now}[1] ) 
    {
        $time--; 
        $ms += 1000000; 
    }
    my $float = sprintf("%06d", $ms - $impl->{now}[1]);
    my $int = strftime( "%H:%M:%S", localtime( $time - $impl->{now}[0] ) 
);
    my $val =  $impl->{val} eq "" ? "" : " [$impl->{val}]";
    return "$int.$float" . $val;
}

sub STORE
{
    my($impl, $val) = @_;
    $val = "" unless defined($val);
    confess "Elapse->lapse() unable to use referenced values"
      if ref($val); 

    $impl->{val} = $val;
    $impl->{now} = [gettimeofday()];
}


sub lapse
{
    tie $_[1], $_[0], $_[1];
}

1;

__END__

=pod

=head1 DESCRIPTION

Elapse.pm is a very simple class with one method: lapse.

Basically, the lapse method 'eats the brains' of the variable,
squirrels away whatever value it may have held internally,
(much like space aliens are known to do in the movies), and also stores 
the current time within it. Then, whenever you access the value of 
the variable, the 'alien' within formats the time *differential*
between when you initialized the variable, and when you printed it, 
and returns that (along with any value the variable may hold, as well). 
:-) 
Every time you print it, you get the updated differential, returned by 
the method hidden inside the variable itself. The output will be 
formatted as HH:MM:SS.000000 [in Microseconds].

=head1 SYNOPSIS

=head2 Usage

To use Elapse.pm is simplicity itself:

    use Elapse;

    # somewhere in your program...
    Elapse->lapse(my $now); 
    # or you can do:
    # Elapse->lapse(my $now = "processing");

    #...rest of program execution

    print "Time Wasted: $now\n";

To update the description and reset the time counter mid-stream, simply 
assign to the variable

    $now = "parsing";

somewhere in the middle of the program. The new value is stored, while 
the original time is replaced with the current time.

=head2 Sample Output

Output looks something like this, using above code:

    Time Wasted: 00:03:05.565763
or
    Time Wasted: 00:00:03.016700 [processing]
    (more output)
    Time Wasted: 00:00:02.003764 [parsing]

=head2 Additional example code

You can also use this during a Net::FTP download loop of files to show 
elapsed time for each file's download. 

  foreach my $file (@files_to_download) 
  {
    # extract localfile name from $file
    # ...
    Elapse->lapse(my $now = "Downloading $localfile.");
    $ftp->get($file, $localfile) or carp("### Could not download $file! 
$!") and next;
    print "Done. Elapsed : $now\n";
    # ...
  }

=head1 'BUGS'

Elapse offers time granularity smaller than 1 second, but values are  
approximate since the accuracy is slightly hampered by the virtue of the 
process itself taking somewhere roughly around 0.0003 - 0.0009 seconds. 
:-) oops.

    #!perl
    use Elapse;
    Elapse->lapse(my $now = "testing 0");
    for (1 .. 5)
    {
        print "$now\n";
        $now = "testing $_";
    }
    print "$now\n";
    
    00:00:00.000937 [testing 0]
    00:00:00.000743 [testing 1]
    00:00:00.000344 [testing 2]
    00:00:00.000327 [testing 3]
    00:00:00.000358 [testing 4]
    00:00:00.000361 [testing 5]


=head1 AUTHOR

=head2 Author

Scott R. Godin, C<E<lt>[EMAIL PROTECTED]<gt>>

=head2 Last Update

Sun, Nov 25, 2001 

=head1 COPYRIGHT

Copyright (c) 2001 Scott R. Godin. All rights reserved. This program is 
free software; you can redistribute it and/or modify it under the same 
terms as Perl itself.


=cut

1;

-- 
Scott R. Godin            | e-mail : [EMAIL PROTECTED]
Laughing Dragon Services  |    web : http://www.webdragon.net/
It is not necessary to cc: me via e-mail unless you mean to speak off-group.
I read these via nntp.perl.org, so as to get the stuff OUT of my mailbox. :-)