/ 
Time-ETA-1.2.0
River stage zero No dependents
/ Time::ETA

NAME

Time::ETA - calculate estimated time of accomplishment

VERSION

version 1.2.0

SYNOPSIS

use Time::ETA;

my $eta = Time::ETA->new(
    milestones => 12,
);

foreach (1..12) {
    do_work();
    $eta->pass_milestone();
    print "Will work " . $eta->get_remaining_seconds() . " seconds more\n";
}

DESCRIPTION

You have a long lasting progress that consist of the number of more or less equal tasks. You need to calculate when the progress will finish. This module is designed to solve this task.

Time::ETA is designed to work with the programms that don't output anything to user console. This module is created to calculate ETA in cron scripts and background running programms. If you need an easy way to output process progress in terminal, please look at the exelent Term::ProgressBar.

To work with Time::ETA you need to create object with constructor new().

Then you run your tasks (just execute subs that containg the code of that tasks) and after each task you run pass_milestone() method to tell Time::ETA object that you have completed part of your process.

Any time in you programme you can use methods to understand what is going on and how soon the process will finish. That are methods is_completed(), get_completed_percent(), get_elapsed_seconds(), get_remaining_seconds().

This module has build-in feature for serialisation. You can run method serialize() to get the text string with the object state. And you can restore your object from that string with spawn() method.

Time::ETA version numbers uses Semantic Versioning standart. Please visit http://semver.org/ to find out all about this great thing.

METHODS

new

Get: 1) $class 2) %params

Return: 1) $self with Time::ETA object

This is the constructor. It needs one mandatory parameter - the number of milestones that should be completed.

Here is the example. Let's imagine that we are generating timetable for the next year. We have method generate_month() that is executed for every month. To create Time::ETA object that can calculate estimated time of timetable generation you need to write:

my $eta = Time::ETA->new(
    milestones => 12,
);

get_elapsed_seconds

Get: 1) $self

Return: 1) $elapsed_seconds - float number

Method return number of seconds that have passed from object creation time.

print $eta->get_elapsed_seconds();

It can output something like 1.35024 and it means that a bit more than one second have passed from the moment the new() constructor has executed.

If the process is finished this method will return process run time in seconds.

get_elapsed_time

Get: 1) $self

Return: 1) $text_time - scalar with the text representation of elapsed time.

Method return elapsed time in the form "H:MM:SS". For example it can return "11:54:12", it means that the process is running for 11 hours, 54 minutes and 12 seconds.

This method returns the same number as get_elapsed_seconds(), but in format that is easy for humans to understand.

get_remaining_seconds

Get: 1) $self

Return: 1) $elapsed_seconds - float number

Method return estimated seconds how long the process will work.

print $eta->get_remaining_seconds();

It can return number like 14.872352 that means that the process will end in nearly 15 seconds. The accuaccuracy of this time depends on the time lengths of every milestone. The more equal milestones time to each other, the more precise is the prediction.

This method will die in case it haven't got enough information to calculate estimated time of accomplishment. The method will die untill pass_milestone() is run for the first time. After pass_milestone() run at least once, get_remaining_seconds() has enouth data to caluate ETA. To find out if ETA can be calculated you can use method can_calculate_eta().

There is one more method that you can use to get information about remaining time. The method is called get_remaining_time(). It return the time in format "H:MM:SS" and works exaclty as this method.

If the process is finished this method will return 0.

get_remaining_time

Get: 1) $self

Return: 1) $text_time - scalar with the text representation of remaing time.

Method return estimated time in the form "H:MM:SS". For example it can return "12:04:44", it means that the process is expected to finish in 12 hours, 4 minutes and 44 seconds.

This method returns the same number as get_remaining_seconds(), but in format that is easy for humans to understand.

Method works the same as get_remaining_seconds(). In case it is not possible to calulate remaining time the method will die. You can use method can_calculate_eta() to find out if it is possible to get remaing time.

If the process is finished this method will return "0:00:00".

get_completed_percent

Get: 1) $self

Return: 1) $completed_percent - float number in the range from zero to 100 (including zero and 100)

Method returns the percentage of the process completion. It will return 0 if no milestones have been passed and it will return 100 if all the milestones have been passed.

$eta->get_completed_percent();

For example, if one milestone from 12 have been completed the method will return 8.33333333333333

is_completed

Get: 1) $self

Return: 1) $boolean - true value if the process is completed or false value if the process is running.

You can also use get_completed_percent() to find our how much of the process is finished.

pass_milestone

Get: 1) $self

Return: it returns nothing that can be used

This method tells the object that one part of the task (called milestone) have been completed. You need to run this method as many times as many milestones you have specified in the object new() constructor.

$eta->pass_milestone();

You need to run this method at least once after start or after resuming (in dependence of what has been happen later) to make method get_remaining_seconds() work.

can_calculate_eta

Get: 1) $self

Return: $boolean

This method returns bool value that gives information if there is enough data in the object to calculate process estimated time of accomplishment.

It will return true value if method pass_milestone() have been run at least once, if the method pass_milestone() haven't been run it will return false.

This method is used to check if it is safe to run method get_remaining_seconds(). Method get_remaining_seconds() dies in case there is no data to calculate ETA.

if ( $eta->can_calculate_eta() ) {
    print $eta->get_remaining_seconds();
}

When the process is complete can_calculate_eta() returns true value, but get_remaining_seconds() return 0.

pause

Get: 1) $self

Return: it returns nothing that can be used

This method tells the object that execution of the task have been paused.

Method dies in case the object is already paused.

$eta->pause();

is_paused

Get: 1) $self

Return: $boolean

This method returns bool value that gives information if the object is paused.

It will return true if method pause() has been run and no resume() method was run after that. Otherwise it will return false.

This method is used to check whether it is safe to run method resume(). Method resume() dies in the case the object is not paused.

if ( $eta->is_paused() ) {
    $eta->resume();
}

resume

Get: 1) $self

Return: it returns nothing that can be used

This method tells the object that execution of the task is continued after pause.

If the object is not paused the method dies.

serialize

Get: 1) $self

Return: 1) $string with serialized object

Object Time::ETA has build-in serialaztion feature. For example you need to store the state of this object in the database. You can run:

my $string = $eta->serialize();

As a result you will get $string with text data that represents the whole object with its state. Then you can store that $string in the database and later with the method spawn() to recreate the object in the same state it was before the serialization.

spawn

Get: 1) $class 2) $string with serialized object

Return: 1) $self

This is actually an object constructor. It recieves $string that contaings serialized object data and creates an object.

my $eta = Time::ETA->spawn($string);

The $string is created by the method serialized().

spawn() die if $string is incorrect. You can check if it is possible to respawn object from a $string with the method can_spawn().

can_spawn

Get: 1) $class 2) $string with serialized object

Return: 1) $bool - true value if it is possible to recreate object from serialized $string, otherwise false value

my $can_spawn = Time::ETA->can_spawn($string);

Methos spawn() that is used to create object from the serialized $string dies in case the $string is incorrect. This method is added to the object to simplify the check process.

SEE ALSO

PBS::ProgressBar
Progress::Any
Progress::PV
Term::ProgressBar::Quiet
Term::ProgressBar::Simple
Term::ProgressBar
Text::ProgressBar::ETA
Time::Progress
http://blogs.perl.org/users/steven_haryanto/2014/02/getting-a-progress-report-from-a-running-program.html

CONTRIBUTORS

  • Dmitry Lukiyanchuk (WTERTIUS)

SOURCE CODE

The source code for this module and scripts is hosted on GitHub https://github.com/bessarabov/Time-ETA

BUGS

Please report any bugs or feature requests in GitHub Issues https://github.com/bessarabov/Time-ETA/issues

AUTHOR

Ivan Bessarabov <ivan@bessarabov.ru>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Ivan Bessarabov.

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