Stopwatch (Performetrics 2.1.1 API)

java.lang.Object
- net.obvj.performetrics.Stopwatch

```
public class Stopwatch
extends Object
```
A convenient timing object that supports multiple counter types.

Use the default constructor, with no arguments, to create a stopwatch with all of the available metrics. If required, an additional constructor may be used to provide a stopwatch with specific counters. E.g.:
```
 new Stopwatch(); // provides all available counter types
 new Stopwatch(Counter.Type.WALL_CLOCK_TIME); // wall-clock time only
 new Stopwatch(Counter.Type.CPU_TIME, Counter.Type.USER_TIME); // two counters
 
```
Note: For a list of available counters, refer to Counter.Type.

Call start() to start the timing session. When you are done, call stop() to complete the timing session.

Hint: A single call to the factory method Stopwatch.createStarted() may create a started stopwatch for convenience.

Use elapsedTime(Counter.Type) to retrieve the elapsed time for a particular counter. E.g.:
```
 double elapsedTimeNanos = cpuTime.elapsedTime(Counter.Type.CPU_TIME, TimeUnit.NANOSECONDS);
 
```
Use the output method printStatistics(System.out) to print stopwatch statistics to the system console.

Although it is intended that the output methods printStatistics() should only be called after the stop, some suitable, temporary data may be returned if the stopwatch is still running. In this scenario, the initial values will be compared to the most up-to-date ones, retrieved at the moment of the call. The same applies to the elapsedTime() methods available for each counter instance.

Note: This class is not thread-safe. In a multi-thread context, different instances must be created for each thread.
Author:

oswaldo.bapvic.jr

See Also:

Counter, Counter.Type

Constructor Summary

Constructors
Constructor and Description
`Stopwatch()` Creates a new stopwatch with default counter types.
`Stopwatch(Counter.Type... types)` Creates a new stopwatch with specific counter types.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Stopwatch`	`createStarted()` Provides a started stopwatch for convenience with default counter types.
`static Stopwatch`	`createStarted(Counter.Type... types)` Provides a started stopwatch for convenience with specific counter types.
`Duration`	`elapsedTime(Counter.Type type)` A convenient method that returns the elapsed time of a specific counter.
`double`	`elapsedTime(Counter.Type type, TimeUnit timeUnit)` A convenient method that returns the elapsed time of a specific counter, in the specified time unit.
`double`	`elapsedTime(Counter.Type type, TimeUnit timeUnit, ConversionMode conversionMode)` A convenient method that returns the elapsed time of a specific counter, in the specified time unit, by applying a custom `ConversionMode`.
`Counter`	`getCounter(Counter.Type type)` Returns the counter instance associated with a given type in this stopwatch.
`Collection<Counter>`	`getCounters()` Returns the counters associated with this stopwatch instance.
`boolean`	`isStarted()` Returns `true` if this stopwatch is started.
`void`	`printStatistics(PrintStream printStream)` Prints stopwatch statistics in the specified print stream.
`void`	`printStatistics(PrintStream printStream, TimeUnit timeUnit)` Prints stopwatch statistics in the specified print stream, with a custom time unit.
`void`	`reset()` Resets all counters associated with this stopwatch instance.
`void`	`start()` Starts the timing session.
`void`	`stop()` Stops the timing session.

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

- Constructor Detail
  - Stopwatch
```
public Stopwatch()
```
    Creates a new stopwatch with default counter types.
  - Stopwatch
```
public Stopwatch(Counter.Type... types)
```
    Creates a new stopwatch with specific counter types.
    
    Parameters:
    
    types - the types to be set
- Method Detail
  - createStarted
```
public static Stopwatch createStarted()
```
    Provides a started stopwatch for convenience with default counter types.
    
    Returns:
    
    a new, started stopwatch
  - createStarted
```
public static Stopwatch createStarted(Counter.Type... types)
```
    Provides a started stopwatch for convenience with specific counter types.
    
    Parameters:
    
    types - the types to be set
    
    Returns:
    
    a new, started stopwatch
  - reset
```
public void reset()
```
    Resets all counters associated with this stopwatch instance.
  - start
```
public void start()
```
    Starts the timing session.
    
    Throws:
    
    IllegalStateException - if the stopwatch state is not suitable for this action
  - stop
```
public void stop()
```
    Stops the timing session.
    
    Throws:
    
    IllegalStateException - if the stopwatch state is not suitable for this action
  - isStarted
```
public boolean isStarted()
```
    Returns true if this stopwatch is started.
    
    Returns:
    
    true if the stopwatch is started; otherwise, false
  - getCounters
```
public Collection<Counter> getCounters()
```
    Returns the counters associated with this stopwatch instance.
    
    Returns:
    
    all counters associated with this stopwatch instance
  - getCounter
```
public Counter getCounter(Counter.Type type)
```
    Returns the counter instance associated with a given type in this stopwatch.
    
    Parameters:
    
    type - the counter type to be fetched
    
    Returns:
    
    the counter instance associated with the given type in this stopwatch
    
    Throws:
    
    IllegalArgumentException - if the specified type is not available in this stopwatch instance
  - elapsedTime
```
public Duration elapsedTime(Counter.Type type)
```
    A convenient method that returns the elapsed time of a specific counter.
    This has the same effect as calling: stopwatch.getCounter(type).elapsedTime()
    
    Parameters:
    
    type - the counter type to be fetched
    
    Returns:
    
    the elapsed time for the specified counter
    
    Throws:
    
    IllegalArgumentException - if the specified type is not available in this stopwatch instance
    
    Since:
    
    2.1.0
  - elapsedTime
```
public double elapsedTime(Counter.Type type,
                          TimeUnit timeUnit)
```
    A convenient method that returns the elapsed time of a specific counter, in the specified time unit.
    This has the same effect as calling: stopwatch.getCounter(type).elapsedTime(timeUnit)
    
    Parameters:
    
    type - the counter type to be fetched
    
    timeUnit - the time unit to which the elapsed time will be converted
    
    Returns:
    
    the elapsed time for the specified counter, converted to the given time unit using the default conversion mode.
    
    Throws:
    
    IllegalArgumentException - if the specified type is not available in this stopwatch instance
    
    Since:
    
    2.1.0
  - elapsedTime
```
public double elapsedTime(Counter.Type type,
                          TimeUnit timeUnit,
                          ConversionMode conversionMode)
```
    A convenient method that returns the elapsed time of a specific counter, in the specified time unit, by applying a custom ConversionMode.
    This has the same effect as calling: stopwatch.getCounter(type).elapsedTime(timeUnit, conversionMode)
    
    Parameters:
    
    type - the counter type to be fetched
    
    timeUnit - the time unit to which the elapsed time will be converted
    
    conversionMode - the ConversionMode to be applied
    
    Returns:
    
    the elapsed time for the specified counter, converted to the given time unit using the given conversion mode.
    
    Throws:
    
    IllegalArgumentException - if the specified type is not available in this stopwatch instance
    
    Since:
    
    2.1.0
  - printStatistics
```
public void printStatistics(PrintStream printStream)
```
    Prints stopwatch statistics in the specified print stream.
    
    Parameters:
    
    printStream - the print stream to which statistics will be sent
  - printStatistics
```
public void printStatistics(PrintStream printStream,
                            TimeUnit timeUnit)
```
    Prints stopwatch statistics in the specified print stream, with a custom time unit.
    
    Parameters:
    
    printStream - the print stream to which statistics will be sent
    
    timeUnit - the time unit for the elapsed times to be displayed

Class Stopwatch

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Stopwatch

Stopwatch

Method Detail

createStarted

createStarted

reset

start

stop

isStarted

getCounters

getCounter

elapsedTime

elapsedTime

elapsedTime

printStatistics

printStatistics