org.objectweb.carol.irmi
Class Timer

java.lang.Object
  extended byorg.objectweb.carol.irmi.Timer

public class Timer
extends java.lang.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)
 

Author:
Rafael H. Schloming <rhs@mit.edu>

Constructor Summary
Timer(java.lang.String name)
          Constructs a new Timer instance with the given unique name.
 
Method Summary
 int getCount()
          Returns the number of start()/stop() pairs accumulated by this Timer instance, not including nested start()/stop() pairs.
 java.lang.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.
 java.lang.String toString()
          Returns a String depicting the total number of milliseconds accumulated by this Timer and the total number of start()/stop() pairs separated by a "/".
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Timer

public Timer(java.lang.String name)
Constructs a new Timer instance with the given unique name.

Parameters:
name - a globally unique name used to distinguish the contents this timer in the timing output
Method Detail

getName

public java.lang.String getName()
Returns the name of this Timer.

Returns:
the Timer name

start

public void start()
Start timing the current thread.


stop

public void stop()
Stop timing the current thread and add the elapsed time to the total count stored by this Timer instance.


getTotal

public long getTotal()
Returns the total time accumulated by this Timer.

Returns:
the total time accumulated by this Timer

getCount

public int getCount()
Returns the number of start()/stop() pairs accumulated by this Timer instance, not including nested start()/stop() pairs.

Returns:
the number of start()/stop() pairs

toString

public java.lang.String toString()
Returns a String depicting the total number of milliseconds accumulated by this Timer and the total number of start()/stop() pairs separated by a "/".

Returns:
"total/count"