|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectit.unimi.dsi.logging.ProgressLogger
public final class ProgressLogger
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 usually 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 LIGHT_UPDATE_MASK
+ 1, in the case of lightUpdate()
).
Other update methods (e.g., update(long)
, updateAndDisplay()
, …) make the update and display process very flexible.
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:
start()
you can get some estimations on the completion time;
displayFreeMemory
you can display information about the
memory usage;
info
you can display arbitrary additional information.
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 );
An instance of this class can also be used as a handy timer:
ProgressLogger pl = new ProgressLogger(); pl.start( "Smashing pumpkins..." ); ... activity on pumpkins (no update() calls) ... pl.done( howManyPumpkins );
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.
Field Summary | |
---|---|
long |
count
The number of calls to update() since the last start() (but it be changed also with update(long) and set(long) ). |
static long |
DEFAULT_LOG_INTERVAL
|
boolean |
displayFreeMemory
Whether to display the free memory at each progress log (default: false). |
long |
expectedUpdates
The number of expected calls to update() (used to compute the percentages, ignored if negative). |
Object |
info
If non- null , this object will be printed after the timing information. |
String |
itemsName
The name of several counted items. |
int |
LIGHT_UPDATE_MASK
Calls to lightUpdate() will cause a call to
System.currentTimeMillis() only if the current value of count
is a multiple of this mask plus one. |
Logger |
logger
The logger used by this progress logger. |
long |
logInterval
The time interval for a new log in milliseconds. |
static long |
ONE_HOUR
|
static long |
ONE_MINUTE
|
static long |
ONE_SECOND
|
Level |
priority
The priority used by this progress logger. |
static long |
TEN_MINUTES
|
static long |
TEN_SECONDS
|
Constructor Summary | |
---|---|
ProgressLogger()
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)
Creates a new progress logger using items as items name and logging every DEFAULT_LOG_INTERVAL milliseconds. |
|
ProgressLogger(Logger logger,
long logInterval)
Creates a new progress logger using items as items name. |
|
ProgressLogger(Logger logger,
long logInterval,
String itemsName)
Creates a new progress logger. |
|
ProgressLogger(Logger logger,
String itemsName)
Creates a new progress logger logging every DEFAULT_LOG_INTERVAL milliseconds. |
Method Summary | |
---|---|
void |
done()
Completes a run of this progress logger, logging “Completed.” and the logger itself. |
void |
done(long count)
Completes a run of this progress logger and sets the internal counter, logging “Completed.” and the logger itself. |
void |
lightUpdate()
Updates the internal count of this progress logger by adding one in a lightweight fashion. |
long |
millis()
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 |
set(long count)
Sets the internal count of this progress logger to a specified value; if enough time has passed since the last log, information will be logged. |
void |
setAndDisplay(long count)
Sets the internal count of this progress logger to a specified value, forcing a display. |
void |
start()
Starts the progress logger, resetting the count. |
void |
start(CharSequence message)
Starts the progress logger, displaying a message and resetting the count. |
void |
stop()
Stops the progress logger. |
void |
stop(CharSequence message)
Stops the progress logger, displaying a message. |
String |
toString()
Converts the data currently stored in this progress logger to a string. |
void |
update()
Updates the internal count of this progress logger by adding one; if enough time has passed since the last log, information will be logged. |
void |
update(long count)
Updates the internal count of this progress logger by adding a specified value; if enough time has passed since the last log, information will be logged. |
void |
updateAndDisplay()
Updates the internal count of this progress logger by adding one, forcing a display. |
void |
updateAndDisplay(long count)
Updates the internal count of this progress logger by adding a specified value, forcing a display. |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final long ONE_SECOND
public static final long TEN_SECONDS
public static final long ONE_MINUTE
public static final long TEN_MINUTES
public static final long ONE_HOUR
public static final long DEFAULT_LOG_INTERVAL
public final int LIGHT_UPDATE_MASK
lightUpdate()
will cause a call to
System.currentTimeMillis()
only if the current value of count
is a multiple of this mask plus one.
public final Logger logger
public Level priority
public long logInterval
public Object info
null
, this object will be printed after the timing information.
public long count
update()
since the last start()
(but it be changed also with update(long)
and set(long)
).
public long expectedUpdates
update()
(used to compute the percentages, ignored if negative).
public String itemsName
public boolean displayFreeMemory
Constructor Detail |
---|
public ProgressLogger()
DEFAULT_LOG_INTERVAL
milliseconds with
to the root logger.
public ProgressLogger(Logger logger)
DEFAULT_LOG_INTERVAL
milliseconds.
logger
- the logger to which messages will be sent.public ProgressLogger(Logger logger, String itemsName)
DEFAULT_LOG_INTERVAL
milliseconds.
logger
- the logger to which messages will be sent.itemsName
- a plural name denoting the counted items.public ProgressLogger(Logger logger, long logInterval)
logger
- the logger to which messages will be sent.logInterval
- the logging interval in milliseconds.public ProgressLogger(Logger logger, long logInterval, String itemsName)
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 |
---|
public void update()
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()
.
public void update(long count)
update()
public void updateAndDisplay()
update()
public void set(long count)
update()
public void setAndDisplay(long count)
update()
public void updateAndDisplay(long count)
update()
public final void lightUpdate()
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 LIGHT_UPDATE_MASK
+ 1. This mechanism makes it possible to reduce the number of
calls to System.currentTimeMillis()
significantly.
This method is useful when the operations being counted take less than a few microseconds.
update()
public void start(CharSequence message)
message
- the message to display.public void start()
public void stop(CharSequence message)
This method will also mark expectedUpdates
as invalid,
to avoid erroneous reuses of previous values.
message
- the message to display.public void stop()
public void done()
public void done(long count)
This method is particularly useful in two circumstances:
start()
and this method.
count
- will replace the internal counter value.public long millis()
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.
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.public String toString()
If this progress logger has been stopped, statistics are computed using the stop time. Otherwise, they are computed using the current time (i.e., the method call time).
toString
in class Object
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |