it.unimi.dsi.mg4j.util
Class ProgressMeter

java.lang.Object
  extended byit.unimi.dsi.mg4j.util.ProgressMeter

public final class ProgressMeter
extends Object

Tunable progress meter.

This class provides a simple way to display progress information about long-lasting activities. It also provides some time measurement.

To use this class, you first create a new meter (possibly specifying a PrintStream to receive the output). The output of the meter depends on the quantum (how many calls to update() cause a dot to be printed) and the items name (the name that will be used to denote counted items). These can be changed at any time with the suitable setters.

To measure the progress of an activity, you call start() at the beginning, which will display the quantum. Then, each time you want to mark progress, you call update(). When the activity is over, you call stop(). At that point, the method toString() returns information about the internal state of the meter (elapsed time, number of items per second) that can be printed or otherwise processed. If update() has never been called, you will just get the elapsed time.

Additionally, by setting the expected amount of updates you can get some estimations on the completion time.

After you finished a run of the meter, you can change its attributes and call start() again to measure another activity.

A typical call sequence to a progress meter is as follows:

 ProgressMeter pm = new ProgressMeter(10, "pumpkins");
 pm.start("Smashing pumpkins...");
 ... activity on pumpkins that calls update() on each pumpkin ...
 pm.done();
 

A more flexible behaviour can be obtained at the end of the process by calling stop():

 ProgressMeter pm = new ProgressMeter(10, "pumpkins");
 pm.start("Smashing pumpkins...");
 ... activity on pumpkins that calls update() on each pumpkin ...
 pm.stop( " really done!" );
 System.err.println( pm );
 

Note that the output stream of the meter is available via the public field out: this makes it possible to pass around a meter and print additional information on the same stream of the meter.

Since:
0.6
Author:
Sebastiano Vigna

Field Summary
 PrintStream out
          The output print stream.
 
Constructor Summary
ProgressMeter()
          Creates a new progress meter with a quantum equal to one, printing on standard error.
ProgressMeter(int quantum)
          Creates a new progress meter with given quantum, printing on standard error.
ProgressMeter(int quantum, String itemsName)
          Creates a new progress meter with given quantum, printing on standard error.
ProgressMeter(int quantum, String itemsName, PrintStream out)
          Creates a new progress meter with given quantum, printing on a given stream.
 
Method Summary
 long count()
          Returns the current count.
 void count(long count)
          Sets the count.
 void done()
          Completes a run of this progress meter, printing " done" and printing this meter itself.
 long expectedUpdates()
          Returns the expected number of updates.
 void expectedUpdates(long num)
          Sets the expected number of updates.
 String itemsName()
          Returns the current items name.
 void itemsName(String itemsName)
          Sets the items name.
static void main(String[] arg)
           
 long millis()
          Returns the number of milliseconds between present time and the last call to start(), if the meter is running, or between the last call to stop() and the last call to start(), if the meter is stopped.
 int quantum()
          Returns the current quantum.
 void quantum(int quantum)
          Sets the quantum.
 void start()
          Starts the progress meter, resetting the count.
 void start(CharSequence message)
          Starts the progress meter, displaying a message and resetting the count.
 void stop()
          Stops the progress meter.
 void stop(CharSequence message)
          Stops the progress meter, displaying a message terminated by a newline.
 String toString()
          Converts the data stored in this meter to a string.
 void update()
          Updates the meter.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

out

public final PrintStream out
The output print stream. It can be used to print information on the same stream used by this progress meter.

Constructor Detail

ProgressMeter

public ProgressMeter()
Creates a new progress meter with a quantum equal to one, printing on standard error.


ProgressMeter

public ProgressMeter(int quantum)
Creates a new progress meter with given quantum, printing on standard error.

Parameters:
quantum - the meter quantum.

ProgressMeter

public ProgressMeter(int quantum,
                     String itemsName)
Creates a new progress meter with given quantum, printing on standard error.

Parameters:
quantum - the meter quantum.
itemsName - a plural name denoting the counted items.

ProgressMeter

public ProgressMeter(int quantum,
                     String itemsName,
                     PrintStream out)
Creates a new progress meter with given quantum, printing on a given stream.

Parameters:
out - a stream that will receive the output of the meter.
quantum - the meter quantum.
itemsName - a plural name denoting the counted items.
Method Detail

update

public void update()
Updates the meter.

This call updates the meter internal count. If the count reaches a multiple of the quantum, a symbol will be printed.


quantum

public void quantum(int quantum)
Sets the quantum.

Parameters:
quantum - the new quantum.

quantum

public int quantum()
Returns the current quantum.

Returns:
the current quantum.

count

public void count(long count)
Sets the count.

Parameters:
count - the new count.

count

public long count()
Returns the current count.

Returns:
the current count.

expectedUpdates

public void expectedUpdates(long num)
Sets the expected number of updates.

Parameters:
num - the new number.

expectedUpdates

public long expectedUpdates()
Returns the expected number of updates.

Returns:
the current expected number of updates.

itemsName

public void itemsName(String itemsName)
Sets the items name.

Parameters:
itemsName - the new items name.

itemsName

public String itemsName()
Returns the current items name.

Returns:
the current items name.

start

public void start(CharSequence message)
Starts the progress meter, displaying a message and resetting the count.

Parameters:
message - the message to display.

start

public void start()
Starts the progress meter, resetting the count.


stop

public void stop(CharSequence message)
Stops the progress meter, displaying a message terminated by a newline.


stop

public void stop()
Stops the progress meter.


done

public void done()
Completes a run of this progress meter, printing " done" and printing this meter itself.


millis

public long millis()
Returns the number of milliseconds between present time and the last call to start(), if the meter is running, or between the last call to stop() and the last call to start(), if the meter is stopped.


toString

public String toString()
Converts the data stored in this meter to a string.

Returns:
the data in this meter in a printable form.

main

public static void main(String[] arg)