it.unimi.dsi.mg4j.util
Class ProgressLogger

java.lang.Object
  extended by it.unimi.dsi.mg4j.util.ProgressLogger

Deprecated. Moved to dsiutils.

@Deprecated
public final class ProgressLogger
extends Object

Tunable progress logger.

This class provides a simple way to log progress information about long-lasting activities.

To use this class, you first create a new instance by passing a Log4J logger, a Priority and a time interval in millisecond (you can use constants such as ONE_MINUTE). Information will be logged about the current state of affairs no more often than the given time interval. The output of the logger depends on the items name (the name that will be used to denote counted items), which can be changed at any time.

To log the progress of an activity, you call start(CharSequence) at the beginning, which will display the given string. Then, each time you want to mark progress, you call update() or lightUpdate(). The latter methods increase the item counter, and will log progress information if enough time has passed since the last log (and if the counter is a multiple of modulus, in the case of lightUpdate()). When the activity is over, you call stop(). At that point, the method toString() returns information about the internal state of the logger (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. By calling done() instead of stop, this information will be logged for you.

Additionally, by setting the expected amount of updates before calling start() you can get some estimations on the completion time.

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

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

 ProgressLogger pl = new ProgressLogger( logger, ProgressLogger.ONE_MINUTE );
 pl.start("Smashing pumpkins...");
 ... activity on pumpkins that calls update() on each pumpkin ...
 pl.done();
 

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

 ProgressLogger pl = new ProgressLogger( logger, ProgressLogger.ONE_MINUTE, "pumpkins" );
 pl.start("Smashing pumpkins...");
 ... activity on pumpkins that calls update() on each pumpkin ...
 pl.stop( "Really done!" );
 pl.logger.log( pl.priority, pm );
 

Should you need to display additional information, you can set the field info to any object: it will be printed just after the timing (and possibly memory) information.

Note that the Log4J logger and priority are available via the public fields logger and priority: this makes it possible to pass around a progress logger and log additional information on the same logging stream. The priority is initialised to Level.INFO, but it can be set at any time.

Since:
0.9.3
Author:
Sebastiano Vigna

Field Summary
 long count
          Deprecated. The number of calls to update() since the last start().
static long DEFAULT_LOG_INTERVAL
          Deprecated.  
 int DEFAULT_MODULUS
          Deprecated. The default modulus for lightUpdate().
 boolean displayFreeMemory
          Deprecated. Whether to display the free memory at each progress log (default: false).
 long expectedUpdates
          Deprecated. The number of expected calls to update() (used to compute the percentages, ignored if negative).
 Object info
          Deprecated. If non-null, this object will be printed after the timinig information.
 String itemsName
          Deprecated. The name of several counted items.
 Logger logger
          Deprecated. The logger used by this progress logger.
 long logInterval
          Deprecated. The time interval for a new log in milliseconds.
 int modulus
          Deprecated. If nonzero, calls to lightUpdate() will cause a call to System.currentTimeMillis() only if the current value of count is a multiple.
static long ONE_HOUR
          Deprecated.  
static long ONE_MINUTE
          Deprecated.  
static long ONE_SECOND
          Deprecated.  
 Level priority
          Deprecated. The priority used by this progress logger.
static long TEN_MINUTES
          Deprecated.  
static long TEN_SECONDS
          Deprecated.  
 
Constructor Summary
ProgressLogger()
          Deprecated. Creates a new progress logger using items as items name and logging every DEFAULT_LOG_INTERVAL milliseconds with to the root logger.
ProgressLogger(Logger logger)
          Deprecated. Creates a new progress logger using items as items name and logging every DEFAULT_LOG_INTERVAL milliseconds.
ProgressLogger(Logger logger, long logInterval)
          Deprecated. Creates a new progress logger using items as items name.
ProgressLogger(Logger logger, long logInterval, String itemsName)
          Deprecated. Creates a new progress logger.
ProgressLogger(Logger logger, String itemsName)
          Deprecated. Creates a new progress logger logging every DEFAULT_LOG_INTERVAL milliseconds.
 
Method Summary
 void done()
          Deprecated. Completes a run of this progress logger, logging Completed. and the logger itself.
 void lightUpdate()
          Deprecated. Updates the progress logger in a lightweight fashion.
 long millis()
          Deprecated. Returns the number of milliseconds between present time and the last call to start(), if this progress logger is running, or between the last call to stop() and the last call to start(), if this progress logger is stopped.
 void start()
          Deprecated. Starts the progress logger, resetting the count.
 void start(CharSequence message)
          Deprecated. Starts the progress logger, displaying a message and resetting the count.
 void stop()
          Deprecated. Stops the progress logger.
 void stop(CharSequence message)
          Deprecated. Stops the progress logger, displaying a message.
 String toString()
          Deprecated. Converts the data stored in this progress logger to a string.
 void update()
          Deprecated. Updates the progress logger.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

ONE_SECOND

public static final long ONE_SECOND
Deprecated. 
See Also:
Constant Field Values

TEN_SECONDS

public static final long TEN_SECONDS
Deprecated. 
See Also:
Constant Field Values

ONE_MINUTE

public static final long ONE_MINUTE
Deprecated. 
See Also:
Constant Field Values

TEN_MINUTES

public static final long TEN_MINUTES
Deprecated. 
See Also:
Constant Field Values

ONE_HOUR

public static final long ONE_HOUR
Deprecated. 
See Also:
Constant Field Values

DEFAULT_LOG_INTERVAL

public static final long DEFAULT_LOG_INTERVAL
Deprecated. 
See Also:
Constant Field Values

DEFAULT_MODULUS

public final int DEFAULT_MODULUS
Deprecated. 
The default modulus for lightUpdate().

See Also:
Constant Field Values

logger

public final Logger logger
Deprecated. 
The logger used by this progress logger.


priority

public Level priority
Deprecated. 
The priority used by this progress logger. It can be changed at any time.


logInterval

public long logInterval
Deprecated. 
The time interval for a new log in milliseconds.


modulus

public int modulus
Deprecated. 
If nonzero, calls to lightUpdate() will cause a call to System.currentTimeMillis() only if the current value of count is a multiple.


info

public Object info
Deprecated. 
If non-null, this object will be printed after the timinig information.


count

public long count
Deprecated. 
The number of calls to update() since the last start().


expectedUpdates

public long expectedUpdates
Deprecated. 
The number of expected calls to update() (used to compute the percentages, ignored if negative).


itemsName

public String itemsName
Deprecated. 
The name of several counted items.


displayFreeMemory

public boolean displayFreeMemory
Deprecated. 
Whether to display the free memory at each progress log (default: false).

Constructor Detail

ProgressLogger

public ProgressLogger()
Deprecated. 
Creates a new progress logger using items as items name and logging every DEFAULT_LOG_INTERVAL milliseconds with to the root logger.


ProgressLogger

public ProgressLogger(Logger logger)
Deprecated. 
Creates a new progress logger using items as items name and logging every DEFAULT_LOG_INTERVAL milliseconds.

Parameters:
logger - the logger to which messages will be sent.

ProgressLogger

public ProgressLogger(Logger logger,
                      String itemsName)
Deprecated. 
Creates a new progress logger logging every DEFAULT_LOG_INTERVAL milliseconds.

Parameters:
logger - the logger to which messages will be sent.
itemsName - a plural name denoting the counted items.

ProgressLogger

public ProgressLogger(Logger logger,
                      long logInterval)
Deprecated. 
Creates a new progress logger using items as items name.

Parameters:
logger - the logger to which messages will be sent.
logInterval - the logging interval in milliseconds.

ProgressLogger

public ProgressLogger(Logger logger,
                      long logInterval,
                      String itemsName)
Deprecated. 
Creates a new progress logger.

Parameters:
logger - the logger to which messages will be sent.
logInterval - the logging interval in milliseconds.
itemsName - a plural name denoting the counted items.
Method Detail

update

public void update()
Deprecated. 
Updates the progress logger.

This call updates the progress logger internal count. If enough time has passed since the last log, information will be logged.

This method is kept intentionally short (it delegates most of the work to an internal private method) so to suggest inlining. However, it performs a call to System.currentTimeMillis() that takes microseconds (not nanoseconds). If you plan on calling this method more than a few thousands times per second, you should use lightUpdate().


lightUpdate

public void lightUpdate()
Deprecated. 
Updates the progress logger in a lightweight fashion.

This call updates the progress logger internal counter as update(). However, it will actually call System.currentTimeMillis() only if the new count is a multiple of modulus. This mechanism makes it possible to reduce the number of calls to System.currentTimeMillis() arbitrarily (e.g., a modulus of 1000 boosts by an order of magnitude the update speed).

This method is useful when the operations being counted take less than a few microseconds.

Throws:
ArithmeticException - if modulus is zero.
See Also:
update()

start

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

Parameters:
message - the message to display.

start

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


stop

public void stop(CharSequence message)
Deprecated. 
Stops the progress logger, displaying a message.

This method will also mark expectedUpdates as invalid, to avoid erroneous reuses of previous values.

Parameters:
message - the message to display.

stop

public void stop()
Deprecated. 
Stops the progress logger.


done

public void done()
Deprecated. 
Completes a run of this progress logger, logging Completed. and the logger itself.


millis

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

Returns:
the number of milliseconds between present time and the last call to start(), if this progress logger is running, or between the last call to stop() and the last call to start(), if this progress logger is stopped.

toString

public String toString()
Deprecated. 
Converts the data stored in this progress logger to a string.

Overrides:
toString in class Object
Returns:
the data in this progress logger in a printable form.