public class Timer extends Object
The Timer class is a utility used to gather timing information about specific operations within a system. It is intended to be lightweight enough that it can be used to gather timing information in a production environment without adversly impacting the performance of the system. It can be used as follows:
private static final Timer OPERATION = new Timer();
private void doOperation() {
OPERATION.start();
try {
...
// do the operation
...
} finally {
OPERATION.stop();
}
}
In order for the timing information gathered by an instance of
this class to be accurate it is necessary that every call to start()
has a corresponding call to stop()
. Because of
this it is good practice to put the call to stop()
in a
finally block as depicted above. This will guarantee proper timing
information even in the event of unanticipated exceptions.
Timer instances track ellapsed time using ThreadLocal storage. This makes it safe for multiple threads to use a single Timer instance to accumulate time. It is important to note that Timer instances track ellapsed real time, not ellapsed CPU time, so if you have 10 threads running simultaneously it is possible for a Timer instance to accumulate 100 seconds even if your program exits after 10 seconds.
Any paired calls to start()
/stop()
that occur
inside an enclosing start()
/stop()
pair for a
given timer instance are not double counted, i.e. it is as if only
the outermost start()
/stop()
pair were invoked.
This behavior allows a Timer instance to be used in a reentrant
manner either inside the body of a recursive function, or across
multiple methods without worrying about double counting when one
timed method invokes another timed method.
If the timer.out system property is specified then at JVM exit the time accumulated by each Timer instance will be printed to the location specified by timer.out. The value of the timer.out system property must be a filename. If the value refers to a file that already exists, the timing information will be appended to the contents of the file, otherwise the file will be created. If "-" is specified for timer.out then the timing results will be displayed on standard error.
The results are displayed by printing for each timer instance: the name of that timer; accumulated time; and number of start()/stop() pairs. The result for each Timer instance is printed on a separate line with the following format.
<NAME>: <millis>/<count>
The default toString()
displays the accumulated
milliseconds and start()
/stop()
count. This
output can be customized by overriding the toString()
method of the Timer instance on construction. This can be useful
for including additional information gathered by your program. For
example if you are timing I/O and you wish to track how many bytes
are written by your program in addition to the standard timing
information then you could use a Timer instance as follows:
private static int bytes = 0;
private static final Timer OUTPUT = new Timer("OUTPUT") {
public String toString() {
return super.toString() + " (" + bytes + " bytes)";
}
}
The code described above will result in the output similar to the following upon JVM termination when the timer.out system property is set:
OUTPUT: 11231/100 (1024861 bytes)
Constructor and Description |
---|
Timer(String name)
Constructs a new Timer instance with the given unique name.
|
Modifier and Type | Method and Description |
---|---|
int |
getCount()
|
String |
getName()
Returns the name of this Timer.
|
long |
getTotal()
Returns the total time accumulated by this Timer.
|
void |
start()
Start timing the current thread.
|
void |
stop()
Stop timing the current thread and add the elapsed time to the
total count stored by this Timer instance.
|
String |
toString()
|
public Timer(String name)
name
- a globally unique name used to distinguish the
contents this timer in the timing outputpublic String getName()
public void start()
public void stop()
public long getTotal()
public int getCount()