Stopwatch (Performetrics 2.2.4 API)

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

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

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 total elapsed time for a particular counter type. E.g.:
```
 Duration cpuTime = stopwatch.elapsedTime(Counter.Type.CPU_TIME);
 
```
Use elapsedTime(Counter.Type, TimeUnit) to retrieve the total elapsed time converted into a specific time unit. E.g.:
```
 double cpuTimeNanos = stopwatch.elapsedTime(Counter.Type.CPU_TIME, TimeUnit.NANOSECONDS);
 
```
Hint: If the stopwatch was created with only one counter type, then no argument is needed to retrieve the total elapsed time. E.g.:
```
 Duration elapsedTime = stopwatch.elapsedTime();
 
```
Use the output methods printSummary(System.out) and printDetails(System.out) to print stopwatch statistics to the system console.

Although it is intended that the output methods elapsedTime(), printSummary(), and printDetails() should be called after the stop, some suitable, temporary data may be returned if the current timing session 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.

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, TimingSession

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 with default counter types, for convenience.
`static Stopwatch`	`createStarted(Counter.Type... types)` Provides a started stopwatch with specific counter types, for convenience.
`Duration`	`elapsedTime()` Returns the total elapsed time for a single counter type, provided that this stopwatch is keeping a single type.
`Duration`	`elapsedTime(Counter.Type type)` Returns the total elapsed time for a specific counter.
`double`	`elapsedTime(Counter.Type type, TimeUnit timeUnit)` Returns the total elapsed time for a specific counter, in the specified time unit.
`double`	`elapsedTime(Counter.Type type, TimeUnit timeUnit, ConversionMode conversionMode)` Returns the total elapsed time for a specific counter, in the specified time unit, with a custom `ConversionMode` applied.
`double`	`elapsedTime(TimeUnit timeUnit)` Returns the total elapsed time in the specified time unit for a single counter type, provided that this stopwatch is keeping a single type.
`double`	`elapsedTime(TimeUnit timeUnit, ConversionMode conversionMode)` Returns the total elapsed time in the specified time unit for a single counter type, provided that this stopwatch is keeping a single type.
`Map<Counter.Type,List<Counter>>`	`getAllCountersByType()` Returns a map of populated counters grouped by type, where each entry in the counters list represents a timing session.
`List<Counter>`	`getCounters(Counter.Type type)` Returns a list of populated counters for a specific type in this stopwatch, or an empty list if no counter is found (for example, if the stopwatch was not yet started, or after reset).
`List<Counter.Type>`	`getTypes()` Returns the counter types associated with this stopwatch instance.
`boolean`	`isStarted()` Returns `true` if this stopwatch is started.
`void`	`printDetails(PrintStream printStream)` Prints detailed information about timing sessions in the specified print stream.
`void`	`printDetails(PrintStream printStream, PrintStyle printStyle)` Prints detailed information about timing sessions in the specified print stream, with a custom `PrintStyle`.
`void`	`printSummary(PrintStream printStream)` Prints summarized elapsed times in the specified print stream.
`void`	`printSummary(PrintStream printStream, PrintStyle printStyle)` Prints summarized elapsed times in the specified print stream, with a custom `PrintStyle`.
`void`	`reset()` Cleans all timing sessions in this stopwatch.
`void`	`start()` Starts a new timing session.
`void`	`stop()` Stops the current timing session.
`String`	`toString()` Returns a string containing a formatted stopwatch summary.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, 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.
    If no type is specified, then all of the available types will be maintained.
    
    Parameters:
    
    types - the types to be set
- Method Detail
  - createStarted
```
public static Stopwatch createStarted()
```
    Provides a started stopwatch with default counter types, for convenience.
    
    Returns:
    
    a new, started stopwatch
  - createStarted
```
public static Stopwatch createStarted(Counter.Type... types)
```
    Provides a started stopwatch with specific counter types, for convenience.
    If no type is specified, then all of the available types will be maintained.
    
    Parameters:
    
    types - the types to be set
    
    Returns:
    
    a new, started stopwatch
  - reset
```
public void reset()
```
    Cleans all timing sessions in this stopwatch.
  - start
```
public void start()
```
    Starts a new timing session.
  - stop
```
public void stop()
```
    Stops the current 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
  - getTypes
```
public List<Counter.Type> getTypes()
```
    Returns the counter types associated with this stopwatch instance.
    
    Returns:
    
    all counter types associated with this stopwatch instance
  - getAllCountersByType
```
public Map<Counter.Type,List<Counter>> getAllCountersByType()
```
    Returns a map of populated counters grouped by type, where each entry in the counters list represents a timing session.
    
    Returns:
    
    a map of populated counters grouped by type
    
    Since:
    
    2.2.1
  - getCounters
```
public List<Counter> getCounters(Counter.Type type)
```
    Returns a list of populated counters for a specific type in this stopwatch, or an empty list if no counter is found (for example, if the stopwatch was not yet started, or after reset).
    
    Parameters:
    
    type - the counter type to be fetched
    
    Returns:
    
    a list of counters associated with the given type, or an empty list
    
    Throws:
    
    IllegalArgumentException - if the specified type was not assigned to the stopwatch during instantiation
    
    Since:
    
    2.2.0
  - elapsedTime
```
public Duration elapsedTime()
```
    Returns the total elapsed time for a single counter type, provided that this stopwatch is keeping a single type.
    
    Returns:
    
    the elapsed time for a single counter type in this stopwatch
    
    Throws:
    
    IllegalStateException - if the stopwatch is keeping more than one counter type
    
    Since:
    
    2.2.4
  - elapsedTime
```
public double elapsedTime(TimeUnit timeUnit)
```
    Returns the total elapsed time in the specified time unit for a single counter type, provided that this stopwatch is keeping a single type.
    
    Parameters:
    
    timeUnit - the time unit to which the elapsed time will be converted
    
    Returns:
    
    the elapsed time for a single counter type in this stopwatch, converted to the given time unit with the default conversion mode
    
    Throws:
    
    IllegalStateException - if the stopwatch is keeping more than one counter type
    
    Since:
    
    2.2.4
  - elapsedTime
```
public double elapsedTime(TimeUnit timeUnit,
                          ConversionMode conversionMode)
```
    Returns the total elapsed time in the specified time unit for a single counter type, provided that this stopwatch is keeping a single type.
    
    Parameters:
    
    timeUnit - the time unit to which the elapsed time will be converted
    
    conversionMode - the ConversionMode to be applied
    
    Returns:
    
    the elapsed time for a single counter type in this stopwatch, converted to the given time unit with the given conversion mode
    
    Throws:
    
    IllegalStateException - if the stopwatch is keeping more than one counter type
    
    Since:
    
    2.2.4
  - elapsedTime
```
public Duration elapsedTime(Counter.Type type)
```
    Returns the total elapsed time for a specific counter.
    
    Parameters:
    
    type - the counter type to be fetched
    
    Returns:
    
    the elapsed time for the specified counter
    
    Throws:
    
    IllegalArgumentException - if the specified type was not assigned to the stopwatch during instantiation
    
    Since:
    
    2.1.0
  - elapsedTime
```
public double elapsedTime(Counter.Type type,
                          TimeUnit timeUnit)
```
    Returns the total elapsed time for a specific counter, in the specified time unit.
    
    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 with the default conversion mode.
    
    Throws:
    
    IllegalArgumentException - if the specified type was not assigned to the stopwatch during instantiation
    
    Since:
    
    2.1.0
  - elapsedTime
```
public double elapsedTime(Counter.Type type,
                          TimeUnit timeUnit,
                          ConversionMode conversionMode)
```
    Returns the total elapsed time for a specific counter, in the specified time unit, with a custom ConversionMode applied.
    
    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 with the given conversion mode.
    
    Throws:
    
    IllegalArgumentException - if the specified type was not assigned to the stopwatch during instantiation
    
    Since:
    
    2.1.0
  - printSummary
```
public void printSummary(PrintStream printStream)
```
    Prints summarized elapsed times in the specified print stream.
    
    Parameters:
    
    printStream - the print stream to which data will be sent
    
    Throws:
    
    NullPointerException - if the PrintStream is null
    
    Since:
    
    2.2.1
  - printSummary
```
public void printSummary(PrintStream printStream,
                         PrintStyle printStyle)
```
    Prints summarized elapsed times in the specified print stream, with a custom PrintStyle.
    
    Parameters:
    
    printStream - the print stream to which data will be sent
    
    printStyle - the PrintStyle to be applied
    
    Throws:
    
    NullPointerException - if the PrintStream is null
    
    IllegalArgumentException - if the specified PrintStyle is not compatible with PrintFormat.SUMMARIZED
    
    Since:
    
    2.2.1
  - printDetails
```
public void printDetails(PrintStream printStream)
```
    Prints detailed information about timing sessions in the specified print stream.
    
    Parameters:
    
    printStream - the print stream to which information will be sent
    
    Throws:
    
    NullPointerException - if the PrintStream is null
    
    Since:
    
    2.2.1
  - printDetails
```
public void printDetails(PrintStream printStream,
                         PrintStyle printStyle)
```
    Prints detailed information about timing sessions in the specified print stream, with a custom PrintStyle.
    
    Parameters:
    
    printStream - the print stream to which information will be sent
    
    printStyle - the PrintStyle to be applied
    
    Throws:
    
    NullPointerException - if the PrintStream is null
    
    IllegalArgumentException - if the specified PrintStyle is not compatible with PrintFormat.DETAILED
    
    Since:
    
    2.2.1
  - toString
```
public String toString()
```
    Returns a string containing a formatted stopwatch summary.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a string containing stopwatch summary
    
    Since:
    
    2.2.4

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

getTypes

getAllCountersByType

getCounters

elapsedTime

elapsedTime

elapsedTime

elapsedTime

elapsedTime

elapsedTime

printSummary

printSummary

printDetails

printDetails

toString