NAME

Time::Spent - Track events and calculate a rolling average of time, er, spent

VERSION

version 0.02

SYNOPSIS

use Time::Spent;

my $tracker = Time::Spent->new( length => 3 );

$tracker->start( 'foo' );
sleep 3;
$tracker->stop( 'foo' );
$tracker->avg; # 3 = 3/1

$tracker->start( 'bar' );
sleep 1;
$tracker->stop( 'bar' );
$tracker->avg; # 2 = (3+1)/2

$tracker->start( 'baz' );
sleep 5;
$tracker->stop( 'baz' );
$tracker->avg; # 3 = (3+1+5)/3;

$tracker->start( 'bat' );
sleep 6;
$tracker->stop( 'bat' );
$tracker->avg; # 4 = (1+5+6)/3


my $tracker = Time::Spent->new( length => 3 );

$tracker->start( 'life' );
sleep 35;
$tracker->start( 'universe' );
sleep 76;
$tracker->start( 'everything' );
sleep 15;

$tracker->stop( 'life', 'universe', 'everything' );
$tracker->avg; # 42 (GET IT?!)

DESCRIPTION

Time::Spent uses a simple rolling average to track tasks by the amount of time they take.

METHODS

new

Create a new Time::Spent object. Accepts one named parameter, length, which must be a positive whole number specifying the number of historical entries to use in the calculation of the rolling average.

Time::Spent->new( length => 30 );

start

Begins tracking for the specified identifiers. Returns the number of new specifiers tracked. Croaks if the identifier is already being tracked or if no identifiers are provided.

$tracker->start( 'ident1', 'ident2', 'ident3' ); # returns 3
$tracker->start( 'ident1' ); # croaks because ident1 is already tracked

stop

Completes tracking for the specified identifiers. The time taken since the call to "start" for each identifier is then added to the historical average time. Removes completed entries' times from tracking as needed to maintain the expected history length. Croaks if any provided identifier is not tracked or if no identifiers are provided.

$tracker->stop( 'ident1' );                      # croaks because ident1 is not tracked
$tracker->start( 'ident1' );
$tracker->stop( 'ident1' );                      # returns 1
$tracker->start( 'ident1', 'ident2', 'ident3' ); # ok because we stopped tracking ident1
$tracker->stop( 'ident1' );                      # returns 1
$tracker->stop( 'ident2', 'ident3' );            # returns 2

avg

Returns the average time taken for tracked identifiers.

is_tracking

Returns true if the identifier passed is currently being tracked (that is, it has been "start"ed but not "stop"ped.

AUTHOR

Jeff Ober <sysread@fastmail.fm>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Jeff Ober.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.