view release on metacpan or  search on metacpan

lib/Log/Any/Progress.pm  view on Meta::CPAN

  }

=head1 DESCRIPTION

This module makes it easy to use L<Log::Any> to log incremental
progress, similar in concept to L<Term::ProgressBar>.  It can be
useful for monitoring the progress of a long-running process and to
get an idea of how long that process might take to finish.

It is generally applied to a processing loop.  In the typical case
where the expected number of iterations is known in advance, it
produces output containing the iteration count, percent completion,
elapsed time, average time per iteration, and estimated time remaining.
For example:

  Progress: Iteration:0/5 0% STARTING
  Progress: Iteration:1/5 20% Elapsed:2.000s Avg:2.000s Remaining:8.001s
  Progress: Iteration:2/5 40% Elapsed:4.001s Avg:2.000s Remaining:6.001s
  Progress: Iteration:3/5 60% Elapsed:6.001s Avg:2.000s Remaining:4.001s
  Progress: Iteration:4/5 80% Elapsed:8.001s Avg:2.000s Remaining:2.000s
  Progress: Iteration:5/5 100% FINISHED Elapsed:10.002s Avg:2.000s

The remaining time estimate as of any particular iteration is a
simple linear calculation based on the average time per iteration up
to that point, and the number of remaining iterations.

If the expected number of iterations is not known in advance, it still
reports on incremental progress, but cannot compute either percent
completion or estimated remaining time.  For example:

  Progress: Iteration:0 STARTING
  Progress: Iteration:1 Elapsed:2.000s Avg:2.000s
  Progress: Iteration:2 Elapsed:4.001s Avg:2.000s
  Progress: Iteration:3 Elapsed:6.001s Avg:2.000s
  Progress: Iteration:4 Elapsed:8.001s Avg:2.000s
  Progress: Iteration:5 Elapsed:10.001s Avg:2.000s

lib/Log/Any/Progress.pm  view on Meta::CPAN

      min_sec_between_messages => 10,
      prefix                   => 'Processing widgets',
  );

Create a new object for logging incremental progress.  Options include:

=over 4

=item count

A mandatory non-zero count of the expected number of iterations for
progress tracking.

Specifying C<-1> indicates that the expected number of iterations is
unknown, in which case abbreviated statistics will be logged for each
iteration (percent completion and estimated finish time cannot be
computed without knowing the expected number of iterations in advance).

=item delayed_start

An optional boolean value controlling whether or not L</start> should
be automatically called at time of object construction.  It defaults
to false, in which case L</start> is automatically called, assuming
that progress tracking will commence immediately after.

Specifying a true value for C<delayed_start> will prevent L</start>
from being automatically called, in which case it should be explicitly

lib/Log/Any/Progress.pm  view on Meta::CPAN

=item min_sec_between_messages

An optional value for the minimum number of seconds to wait before
emitting the next incremental progress log message (as a result of
calling L</update>).  Values specifying fractional seconds are allowed
(e.g. C<0.5>).  It defaults to C<10> seconds.

Setting C<min_sec_between_messages> appropriately can be used to
control log verbosity in cases where many hundreds or thousands of
iterations are being processed and it's not necessary to report after
each iteration.  Setting it to C<0> will result in every incremental
progress message will be emitted.

=item prefix

An optional string which will be used to prefix each logged message.
It defaults to C<Progress>.

=back