MemoryWatch

java.lang.Object
- org.mitre.poorMan.javaTiming.Statistic
- - org.mitre.poorMan.javaTiming.MemoryWatch

All Implemented Interfaces:

java.lang.Comparable<org.mitre.poorMan.javaTiming.HasName>
```
public class MemoryWatch
extends Statistic
```
Keeps an eye on memory utilization. This invokes Runtime.totalMemory() and Runtime.freeMemory() as needed. If you enableGCBeforeStartStop() the this will also cause calls to Runtime.gc(). Beware that stops and starts may have significant and unpredictable overhead. Use with care.
Use Timing.createMemoryWatch(String) to create.

Version:

1.2

Author:

Nazario Irizarry (naz)

Field Summary
- Fields inherited from class org.mitre.poorMan.javaTiming.Statistic
  count, enableMinMax, enableStdDev

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clearCumulative()` Resets cumulative time and count to zero.
`void`	`clearCumulative(boolean silently)` Resets cumulative time and count to zero.
`int`	`compareTo(org.mitre.poorMan.javaTiming.HasName ot)`
`static long`	`currentUsage()` Convenience method to get the current total memory - the current free memory.
`MemoryWatch`	`enableGCBeforeStartStop()` Enable attempted memory recovery before every start() and stop().
`MemoryWatch`	`enableMinMax()` Enable tracking of min and max.
`MemoryWatch`	`enableStdDev()` Enable computation of standard deviation.
`boolean`	`equals(java.lang.Object o)` Equality is determined by a unique id which is assigned upon instantiation.
`java.lang.String`	`getCompositeName()`
`java.lang.String`	`getLocationInCodeString()` The returned string reflects the java class, method, and line number at which the StopWatch was created.
`java.lang.String`	`getName()`
`long`	`getStartMemory()` The memory usage upon start.
`protected int`	`getUniqueId()`
`int`	`hashCode()`
`boolean`	`isStarted()`
`static void`	`recoverMemory()` Instruct java to cleanup memory.
`MemoryWatch`	`setUnits(java.lang.String units, double multiplier)` Specify the units and the multiplier to use.
`MemoryWatch`	`start()` Starts the counter in nanoseconds
`MemoryWatch`	`startAtSameMemAs(MemoryWatch other)` Set the start memory to be the same as that of another.
`void`	`stop()` Stops the counter, advances the count by one, and adds to the accumulated memory
`void`	`stop(int countIncrement)` Stops the counter, adds to the accumulated memory, and adds the specified count increment (instead of 1) to the count.
`java.lang.String`	`summarize()`
`void`	`summarize(java.util.Formatter formatter)` Builds a summary of the metric
`void`	`summarize(java.lang.StringBuilder sb)` Appends a summary line for the metric using the specified StringBuilder.
`MemoryWatch`	`suppressIfCountIsZero()` This indicates that the MemoryWatch summary line should not be output to the screen with `Timing.dumpTimings(java.lang.String)` is called if the `getCount()` value is zero.
`MemoryWatch`	`suppressIfValueIsZero()` This indicates that the MemoryWatch summary line should not be output to the screen with `Timing.dumpTimings(java.lang.String)` is called if the `getCount()` value is zero.
`void`	`tallyAndContinue()` Stops the counter and restarts it in such a way that no time is lost between stop and start.
`java.lang.String`	`toString()`

Methods inherited from class org.mitre.poorMan.javaTiming.Statistic
addCount, addDelta, addDelta, addDelta, addDelta, getAvg, getCoefOfVariation, getCount, getCumulative, getMax, getMin, getStdDev, reset

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

- Method Detail
  - getStartMemory
```
public final long getStartMemory()
```
    The memory usage upon start.
    
    Returns:
    usage in bytes
  - setUnits
```
public final MemoryWatch setUnits(java.lang.String units,
                   double multiplier)
```
    Specify the units and the multiplier to use. Internal memory is tracked in bytes and the default units are bytes. The default multiplier is 1. This is especially useful if you are adding statistics with the addDelta() method because what you add will be in your own units.
  - currentUsage
```
public static long currentUsage()
```
    Convenience method to get the current total memory - the current free memory. Does not cause calls to Runtime.gc().
    
    Returns:
    current memory usage.
  - start
```
public final MemoryWatch start()
```
    Starts the counter in nanoseconds
  - startAtSameMemAs
```
public final MemoryWatch startAtSameMemAs(MemoryWatch other)
```
    Set the start memory to be the same as that of another. This can be helpful if you are starting two MemoryWatches sequentially and want them to use the same starting memory.
  - enableGCBeforeStartStop
```
public final MemoryWatch enableGCBeforeStartStop()
```
    Enable attempted memory recovery before every start() and stop(). This is done by first calling the recoverMemory() method. Note that the recover method intentionally does Thread.sleep() so this should not be enabled if you are debugging critical timing.
  - stop
```
public final void stop()
```
    Stops the counter, advances the count by one, and adds to the accumulated memory
  - stop
```
public final void stop(int countIncrement)
```
    Stops the counter, adds to the accumulated memory, and adds the specified count increment (instead of 1) to the count. Note that the standard deviation statistics will not be correct if this is used.
  - isStarted
```
public final boolean isStarted()
```
    Returns:
    true if started.
  - summarize
```
public void summarize(java.util.Formatter formatter)
```
    Builds a summary of the metric
  - suppressIfCountIsZero
```
public final MemoryWatch suppressIfCountIsZero()
```
    This indicates that the MemoryWatch summary line should not be output to the screen with Timing.dumpTimings(java.lang.String) is called if the getCount() value is zero. Once this call is invoked its effect cannot be undone.
  - suppressIfValueIsZero
```
public final MemoryWatch suppressIfValueIsZero()
```
    This indicates that the MemoryWatch summary line should not be output to the screen with Timing.dumpTimings(java.lang.String) is called if the getCount() value is zero. Once this call is invoked its effect cannot be undone.
  - tallyAndContinue
```
public final void tallyAndContinue()
```
    Stops the counter and restarts it in such a way that no time is lost between stop and start. If you simply invoked myMemoryWatch.stop() followed by myMemoryWatch.start() there is a chance that the nanosecond timer will advance and you will appear to have time unaccounted for. This can be helpful in loops where you wish to measure each iteration of the loop and are carefully accounting for all elapsed time.
  - recoverMemory
```
public static void recoverMemory()
```
    Instruct java to cleanup memory. Note that there is no perfect way to do this as we can't control the garbage collector. This implementation loops invoking the Runtime.gc() method a few times until there is a downward change. However, if there is none after about 10 iterations this simply returns.
  - enableStdDev
```
public MemoryWatch enableStdDev()
```
    Enable computation of standard deviation.
    
    Overrides:
    
    enableStdDev in class Statistic
    
    Returns:
    instance of this
  - enableMinMax
```
public MemoryWatch enableMinMax()
```
    Enable tracking of min and max.
    
    Overrides:
    
    enableMinMax in class Statistic
    
    Returns:
    instance of this
  - clearCumulative
```
public final void clearCumulative(boolean silently)
```
    Resets cumulative time and count to zero. Also clears the internal count of concurrency problem reports that my have been written to the log file.
    
    Parameters:
    silently - if false then a message is written to the log file indicating that the StopWatch was cleared.
  - clearCumulative
```
public final void clearCumulative()
```
    Resets cumulative time and count to zero. Also clears the internal count of concurrency problem reports that my have been written to the log file. Same as clearCumulative(true)
  - compareTo
```
public final int compareTo(org.mitre.poorMan.javaTiming.HasName ot)
```
    Specified by:
    
    compareTo in interface java.lang.Comparable<org.mitre.poorMan.javaTiming.HasName>
  - equals
```
public boolean equals(java.lang.Object o)
```
    Equality is determined by a unique id which is assigned upon instantiation.
    
    Overrides:
    
    equals in class java.lang.Object
  - getCompositeName
```
public java.lang.String getCompositeName()
```
    Returns:
    a concatenation of the name and location-in-code string
  - getLocationInCodeString
```
public java.lang.String getLocationInCodeString()
```
    The returned string reflects the java class, method, and line number at which the StopWatch was created.
  - getName
```
public java.lang.String getName()
```
    Returns:
    the "print" name
  - getUniqueId
```
protected int getUniqueId()
```
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - summarize
```
public void summarize(java.lang.StringBuilder sb)
```
    Appends a summary line for the metric using the specified StringBuilder.
  - summarize
```
public java.lang.String summarize()
```
    Returns:
    a summary line of this metric with all its parts

Class MemoryWatch

Field Summary

Fields inherited from class org.mitre.poorMan.javaTiming.Statistic

Method Summary

Methods inherited from class org.mitre.poorMan.javaTiming.Statistic

Methods inherited from class java.lang.Object

Method Detail

getStartMemory

setUnits

currentUsage

start

startAtSameMemAs

enableGCBeforeStartStop

stop

stop

isStarted

summarize

suppressIfCountIsZero

suppressIfValueIsZero

tallyAndContinue

recoverMemory

enableStdDev

enableMinMax

clearCumulative

clearCumulative

compareTo

equals

getCompositeName

getLocationInCodeString

getName

getUniqueId

hashCode

toString

summarize

summarize