org.jmonit
Class Stopwatch

java.lang.Object
  org.jmonit.Probe
      org.jmonit.Stopwatch

Direct Known Subclasses:

LocalStopwatch

public class Stopwatch
extends Probe

a Stopwatch is used to evaluate the time consumed by a thread to execute some process. There is two way to use a Stopwatch :

• By using the start(Monitor) method to create a new instance. The returned object is not thread-safe and must be created on every thread that execute the code to be monitored.
By getting a Stopwatch usin the monitor features API using monitor.getFeature(Stopwatch.class). In such case, the Stopwatch object can be reused, and can also be obtained from another block of code. It internally uses a threadLocale to associate the running Stopwatch with the current active thread.

In both case, the monitored application MUST allways stop(boolean) or cancel() even when an error occurs. For this reason, a try/catch is highly recommended.

If not followed, this requirement will introduce zombie threads in Concurrency and invalid performance statistics. You will also get warning in logs for zombie Stopwatches.

Author:

Nicolas De Loof

Constructor Summary

Stopwatch()
Default constructor.

Stopwatch(Monitor monitor)
Constructor

Method Summary

void	cancel() Cancel monitoring.
protected void	finalize() Monitored application should use a try/finally block to ensure on of stop() or cancel() method is invoked, even when an exception occurs.
protected void	fireMonitoringEvent(MonitoringEvent event)
long	getElapsedTime()
boolean	isPaused()
boolean	isStarted()
boolean	isStoped()
protected long	nanotime() Returns the current value of the most precise available system timer, in nanoseconds.
void	pause() Temporary stop the Stopwatch.
void	resume() Resume the Stopwatch after a pause.
void	start() Start monitoring the process.
static Stopwatch	start(Monitor monitor) Start a new Stopwatch to evaluate time consumed to execute some processing.
long	stop() Stop monitoring the process.
long	stop(boolean canceled) Convenience method to stop or cancel a Stopwatch depending on success of monitored operation

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Stopwatch

public Stopwatch(Monitor monitor)

Constructor

Parameters:

monitor - monitor that gets the elapsed time to be monitored

Stopwatch

public Stopwatch()

Default constructor. Can be used to evalutate execution time without monitoring.

Method Detail

start

public static Stopwatch start(Monitor monitor)

Start a new Stopwatch to evaluate time consumed to execute some processing. The created object is not thread-safe and must be garbaged after use.

Parameters:

monitor - the monitor used to gather the computed execution time

Returns:

a new started Stopwatch

cancel

public void cancel()

Cancel monitoring. Elapsed time will not be computed and will not be published to the monitor.

In some circumstances you want to monitor time elapsed from early stage of computation, and discover latter if the computed data is relevant. For example, monitoring a messaging system, but beeing interested only by some types of messages. In such case, a Stopwatch can be started early and canceled when the application is able to determine it's relevancy.

In any way, the probe will still report thread concurrency even if canceled.

Overrides:

cancel in class Probe

getElapsedTime

public long getElapsedTime()

Overrides:

getElapsedTime in class Probe

Returns:

Elapsed time (in nanoseconds) for the monitored process

pause

public void pause()

Temporary stop the Stopwatch. Elapsed time calculation will not include time spent in paused mode.

Overrides:

pause in class Probe

resume

public void resume()

Resume the Stopwatch after a pause.

Overrides:

resume in class Probe

start

public void start()

Start monitoring the process.

Overrides:

start in class Probe

fireMonitoringEvent

protected void fireMonitoringEvent(MonitoringEvent event)

stop

public long stop(boolean canceled)

Convenience method to stop or cancel a Stopwatch depending on success of monitored operation

Overrides:

stop in class Probe

Parameters:

canceled -

Returns:

time elapsed since the probe has been started

stop

public long stop()

Stop monitoring the process. A Stopwatch created with start(Monitor) cannot be re-used after stopped has been called.

Overrides:

stop in class Probe

finalize

protected void finalize()

Monitored application should use a try/finally block to ensure on of stop() or cancel() method is invoked, even when an exception occurs. To avoid Stopwatches to keep running if the application didn't follow this recommandation, the finalizer is used to cancel the Stopwatch and will log a educational warning.

Overrides:

finalize in class java.lang.Object

See Also:

Object.finalize()

nanotime

protected long nanotime()

Returns the current value of the most precise available system timer, in nanoseconds. The real precision depends on the JVM and the underlying system. On JRE before java5, backport-util-concurrent provides some limited support for equivalent timer.

Returns:

time in nanosecond

See Also:

System.nanoTime()

isStarted

public boolean isStarted()

Returns:

true if the Stopwatch has been started

isStoped

public boolean isStoped()

Returns:

true if the Stopwatch has been stopped

isPaused

public boolean isPaused()

Returns:

true if the Stopwatch has been paused