Timing

java.lang.Object
- org.mitre.poorMan.javaTiming.Timing

```
public class Timing
extends java.lang.Object
```
Methods to instrument code to track selected code paths.

Author:

Nazario Irizarry

Field Summary

Fields
Modifier and Type	Field and Description
`static org.mitre.poorMan.javaTiming.LogTarget`	`logTarget`
`static double`	`startStopOverhead`
`static java.lang.String`	`TIME_FORMAT` The format used to output absolute time: "%1$TH:%1$TM:%1$TS.%1$TL" The format can be changed at runtime.

Method Summary

Methods
Modifier and Type	Method and Description
`static double`	`adjustedAvg(StopWatch sw)` Convenience method that subtracts the estimated start/stop overhead from the stop watch's average.
`static void`	`clearAll()` Clear timers and statistics.
`static void`	`clearAll(java.lang.String message)` Clear timers and statistics and write out a message.
`static void`	`clearAllTersely(java.lang.String message)` Clear timers and statistics and write out a message Don't warn if there are no registered timings.
`static MemoryWatch`	`createMemoryWatch(java.lang.String name)` Create a MemoryWatch and register it.
`static StopWatch`	`createStopWatch(java.lang.String name)` Create a StopWatch and register it.
`static long`	`determineNanosecondGranularity()` This will determine the granularity of your system's nanosecond clock by "spinning" in a loop looking for rollover in the time reported by System.nanoTime().
`static Statistic`	`determineNanosecondJitterMinMax()` This will get 1000 successive readings from the nanosecond clock to compute its statistics.
`static java.lang.Object`	`dumpTimings(java.lang.String message)` Dump all registered timings to the log.
`static double`	`estimateStartStopOverhead()` Iteratively (100,000 times) invokes StopWatch.start() followed by StopWatch.stop() to determine the average overhead for these calls.
`static double`	`estimateStartStopOverhead(StopWatch sw)` Iteratively (100,000 times) invokes sw.start() followed by sw.stop() to determine the average overhead for these calls.
`static java.lang.String`	`formattedCurrentTime()` Returns the current time in the current time format.
`static java.lang.String`	`formattedCurrentTime(long time)` Returns the specified time in the current time format.
`static void`	`memoryLog(java.lang.Object o)` Sometimes you want to add notes to the output log without incurring the overhead of I/O at the time.
`static void`	`pause(long millis)` A convenience method to sleep for the specified time
`static void`	`printP(java.lang.Object o)` Logs the message by invoking o.toString() and adds the time to the end of the line using the `TIME_FORMAT` format.
`static void`	`printP(java.lang.String msg)` Logs the message and adds the current time to the end of the line using the `TIME_FORMAT` format.
`static void`	`printP(java.lang.String msg, long time)` Logs the message and adds the time to the end of the line using the `TIME_FORMAT` format.
`static void`	`registerDerivedComputation(java.lang.String name, DerivedComputation computation)` Register a DerivedComputation.
`static void`	`setStopWatchFactory(StopWatchFactory factory)` Replaces the default factory with your own.
`static void`	`stopStart(StopWatch timeToStop, StopWatch timeToStart)` This ensures that the same time is used to stop a previous timer and restart another one.
`static void`	`stripBaseName(java.lang.String baseName)` Base names are stripped from the output generated by dumpTimings() to clean up the output of redundant text.
`static void`	`summarizeAverageFirstByDefault()` Set the default summary for new stop watches.
`static void`	`summarizeCumulativeFirstByDefault()` Set the default summary for new stop watches.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - startStopOverhead
```
public static double startStopOverhead
```
  - logTarget
```
public static org.mitre.poorMan.javaTiming.LogTarget logTarget
```
  - TIME_FORMAT
```
public static java.lang.String TIME_FORMAT
```
    The format used to output absolute time: "%1$TH:%1$TM:%1$TS.%1$TL" The format can be changed at runtime.
- Method Detail
  - adjustedAvg
```
public static double adjustedAvg(StopWatch sw)
```
    Convenience method that subtracts the estimated start/stop overhead from the stop watch's average.
    
    Parameters:
    sw -
    
    Returns:
    corrected average
    
    Throws:
    
    java.lang.IllegalStateException - if the average is less than the overhead
  - summarizeCumulativeFirstByDefault
```
public static void summarizeCumulativeFirstByDefault()
```
    Set the default summary for new stop watches. Causes the output from Watch.summarize() to first show the cumulative, then the average.
  - summarizeAverageFirstByDefault
```
public static void summarizeAverageFirstByDefault()
```
    Set the default summary for new stop watches. Cause the output from Watch.summarize() to first show the average then the cumulative.
  - clearAll
```
public static void clearAll()
```
    Clear timers and statistics. There are no log messages or warnings generated.
  - clearAll
```
public static void clearAll(java.lang.String message)
```
    Clear timers and statistics and write out a message. Warn if there are no registered timings.
  - clearAllTersely
```
public static void clearAllTersely(java.lang.String message)
```
    Clear timers and statistics and write out a message Don't warn if there are no registered timings.
  - createMemoryWatch
```
public static MemoryWatch createMemoryWatch(java.lang.String name)
```
    Create a MemoryWatch and register it. A simple MemoryWatch just starts, stops. It accumulates memory usage and counts the number of times it was stopped.
    The difference between createMemoryWatch() and createMemoryStatistic() is that the former reports cumulative memory in the output and the number of iterations. The latter reports average time as well as other statistics. Unlike time, memory usage can be negative if the garbage collector reclaims memory. Thus the average may be zero though the variance could be big.
    Beware that a MemoryWatch is identified by its name. If you call this method more than once with the same name the MemoryWatch that is returned will be the same!
    The idea is to conditionally compile the logic so you can essentially remove it from the runtime when you are not debugging.
    Typical code would be:
```
 static final boolean WATCH_MEMORY = true;
 MemoryWatch myMem = null;

 ...

 if (WATCH_MEMORY) {
     if (myMem == null){
         myMem = Timing.createAndRegister("memory usage");
     }
     myMem.start();
 }

 .... work done here ...

 if (WATCH_MEMORY) {
     myMem.stop();
 }

 
```
    Throws:
    
    java.lang.IllegalStateException - if a StopWatch with the same name has already been created.
  - createStopWatch
```
public static StopWatch createStopWatch(java.lang.String name)
```
    Create a StopWatch and register it. A simple StopWatch just starts, stops. It accumulates time and counts the number of times it was stopped. It reports cumulative time in the output and the number of iterations.
    Once created a StopWatch can be turned into a statistic by invoking its enableStdDev() method. Then it will report average time and standard deviation.
    Beware that a StopWatch is identified by its name. If you call this method more than once with the same name the StopWatch that is returned will be the same!
    The idea is to conditionally compile the timing logic so you can essentially remove it from the runtime when you are not debugging.
    Typical code would be:
```
 static final boolean DO_TIMING = true;
 StopWatch myTiming = null;

 ...

 if (DO_TIMING) {
     if (myTiming == null){
         myTiming = Timing.createAndRegister("start of my task");
     }
     myTiming.start();
 }

 .... work done here ...

 if (DO_TIMING) {
     myTiming.stop();
 }

 
```
    Throws:
    
    java.lang.IllegalStateException - if there is a MemoryWatch with the same name.
  - determineNanosecondGranularity
```
public static long determineNanosecondGranularity()
```
    This will determine the granularity of your system's nanosecond clock by "spinning" in a loop looking for rollover in the time reported by System.nanoTime(). Nine rollover times are measured and the median is returned.
    
    Returns:
    the resolution in nanoseconds.
  - determineNanosecondJitterMinMax
```
public static Statistic determineNanosecondJitterMinMax()
```
    This will get 1000 successive readings from the nanosecond clock to compute its statistics. The returned Statistic has average/min/max/standard deviation in nanoseconds.
    
    Returns:
    the Statistic in nanoseconds.
  - dumpTimings
```
public static java.lang.Object dumpTimings(java.lang.String message)
```
    Dump all registered timings to the log. If the call graph was enabled then we also dump the call graph and associated timings.
  - estimateStartStopOverhead
```
public static double estimateStartStopOverhead()
```
    Iteratively (100,000 times) invokes StopWatch.start() followed by StopWatch.stop() to determine the average overhead for these calls. A simple stopwatch without standard deviation and min/max tracking is used. This method caches the result. Subsequent calls after the first invocation simply return the cached result.
    
    Returns:
    the estimated time in nanoseconds
  - estimateStartStopOverhead
```
public static double estimateStartStopOverhead(StopWatch sw)
```
    Iteratively (100,000 times) invokes sw.start() followed by sw.stop() to determine the average overhead for these calls. This method just uses the stopWatch to accumulate statistics. The statistics are not cleared when done. Thus if standard deviation is enabled the stopwatch can be queried after the fact to estimate measurement jitter as well.
    
    Parameters:
    sw - the StopWatch to use
    
    Returns:
    the estimated time in nanoseconds
  - formattedCurrentTime
```
public static java.lang.String formattedCurrentTime()
```
    Returns the current time in the current time format.
    
    Returns:
    the current time in the time format
    See Also:
    TIME_FORMAT
  - formattedCurrentTime
```
public static java.lang.String formattedCurrentTime(long time)
```
    Returns the specified time in the current time format.
    
    Returns:
    format time using the time format
    See Also:
    TIME_FORMAT
  - memoryLog
```
public static void memoryLog(java.lang.Object o)
```
    Sometimes you want to add notes to the output log without incurring the overhead of I/O at the time. The object passed in is converted to a String using o.toString() but it is added to a memory buffer. The contents of the memory buffer are dumped later when you invoke dumpTimings().
    
    Parameters:
    o - Object to invoke toString() on
  - pause
```
public static void pause(long millis)
```
    A convenience method to sleep for the specified time
    
    Parameters:
    millis -
  - printP
```
public static void printP(java.lang.Object o)
```
    Logs the message by invoking o.toString() and adds the time to the end of the line using the TIME_FORMAT format.
  - printP
```
public static void printP(java.lang.String msg)
```
    Logs the message and adds the current time to the end of the line using the TIME_FORMAT format.
  - printP
```
public static void printP(java.lang.String msg,
          long time)
```
    Logs the message and adds the time to the end of the line using the TIME_FORMAT format.
    
    Parameters:
    msg -
    time -
  - registerDerivedComputation
```
public static void registerDerivedComputation(java.lang.String name,
                              DerivedComputation computation)
```
    Register a DerivedComputation. The summary string for the computation is output when dumpTimings() is invoked.
    
    Parameters:
    name - Used as part of the output.
    computation - The DerivedComputation
  - setStopWatchFactory
```
public static void setStopWatchFactory(StopWatchFactory factory)
```
    Replaces the default factory with your own.
    
    Parameters:
    factory -
  - stopStart
```
public static void stopStart(StopWatch timeToStop,
             StopWatch timeToStart)
```
    This ensures that the same time is used to stop a previous timer and restart another one. This is for where it is important to exactly account for each and every nanosecond spent on a sequence of timing events.
    
    Parameters:
    timeToStop - - this one is stopped
    timeToStart - - this one is started
  - stripBaseName
```
public static void stripBaseName(java.lang.String baseName)
```
    Base names are stripped from the output generated by dumpTimings() to clean up the output of redundant text. For example, if all your packages have a common prefix such as "org.mitre" then you could add that to simplify the output.
    There can be multiple names stripped, with multiple calls to this method.
    This is optional. A base name does not have to be specified.
    
    Parameters:
    baseName -

Class Timing

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

startStopOverhead

logTarget

TIME_FORMAT

Method Detail

adjustedAvg

summarizeCumulativeFirstByDefault

summarizeAverageFirstByDefault

clearAll

clearAll

clearAllTersely

createMemoryWatch

createStopWatch

determineNanosecondGranularity

determineNanosecondJitterMinMax

dumpTimings

estimateStartStopOverhead

estimateStartStopOverhead

formattedCurrentTime

formattedCurrentTime

memoryLog

pause

printP

printP

printP

registerDerivedComputation

setStopWatchFactory

stopStart

stripBaseName