Package eu.bandm.tools.util.java

Class ProgressTracker

java.lang.Object
eu.bandm.tools.util.java.ProgressTracker
All Implemented Interfaces:
AutoCloseable
public class ProgressTracker extends Object implements AutoCloseable
Tracks the progress of a hierarchical task.

Progress is quantified as a floating-point number in the unit interval, i.e., between 0.0 and 1.0, both inclusive.

Progress is supposed, but not enforced, to be non-decreasing over time.

The progress of a task can be updated in either of two ways:

  • Directly by setting to a specific value, if the task is conceptually atomic, or or
  • indirectly by subdividing the task into a sequence of subtasks and assigning weights to those. Every subtask is issued with a local tracker, such that local progress values always use the same scale.

The progress of a whole task can be monitored actively by repeatedly calling getProgress(), or passively by passing a hook function object that is called back on any change.

  • Constructor Details

    • ProgressTracker

      public ProgressTracker(double resolution, @Opt @Opt DoubleConsumer hook)
      Creates a new tracker for a whole task.

      A desired resolution can be specified, in order that there are not too many change events for highly (especially recursively) subdivided tasks: If the effective contribution of a subtask is less than or equal to the resolution, then its partial progress will not be propagated to its supertasks, only its completion. Set the resolution to 0.0 for maximum detail.

      Parameters:
      resolution - the desired resolution of the tracking process
      hook - the hook operation to execute whenever progress changes, or null if not applicable
      Throws:
      IllegalArgumentException - if resolution is outside the unit interval

  • Method Details

    • subdivideEqually

      public ProgressTracker[] subdivideEqually(int n)
      Creates an array of trackers for subtasks of equal weight.

      It is assumed that the subtasks are performed in sequence: A report for the (i+1)-th subtracker, even with progress value 0.0, implies that the i-th subtask has already been completed.

      Parameters:
      n - the number of subtasks
      Throws:
      IllegalArgumentException - if n is nonpositive

    • subdivide

      public ProgressTracker[] subdivide(double... weights)
      Creates an array of trackers for subtasks of arbitrary weights.

      It is assumed that the subtasks are performed in sequence.

      Parameters:
      weights - the weights of all but the last subtask
      Throws:
      IllegalArgumentException - if any element of weights is outside the unit interval, or if the sum of weights is greater than 1.0

    • reset

      public void reset()

    • close

      public void close()
      Report that the tracked task is completed.

      This method has the same effect as report(double) with an argument of 1.0.

      For consistency of monitoring, it is good practice to call this method eventually for any tracker that has been created, even if the accumulated progress of its subtasks may already sum to 1.0.

      Specified by:
      close in interface AutoCloseable

    • report

      public void report(double progress)
      Report that the tracked task has reached a specific progress value.

      Progress will be propagated to the parent task, if there is one. Partial progress, i.e., values less than 1.0 are not propagated if below the resolution threshold.

      Parameters:
      progress - the achieved progress value
      Throws:
      IllegalArgumentException - if progress is outside the unit interval

    • getProgress

      public double getProgress()
      Returns the current progress value.