StopWatch (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3.time, class: StopWatch

# Class StopWatch

java.lang.Object
org.apache.commons.lang3.time.StopWatch

public class StopWatch extends Object
`StopWatch` provides a convenient API for timings.

To start the watch, call `start()` or `createStarted()`. At this point you can:

- `split()` the watch to get the time whilst the watch continues in the background. `unsplit()` will remove the effect of the split. At this point, these three options are available again.
- `suspend()` the watch to pause it. `resume()` allows the watch to continue. Any time between the suspend and resume will not be counted in the total. At this point, these three options are available again.
- `stop()` the watch to complete the timing session.

It is intended that the output methods `toString()` and `getTime()` should only be called after stop, split or suspend, however a suitable result will be returned at other points.

NOTE: As from v2.1, the methods protect against inappropriate calls. Thus you cannot now call stop before start, resume before suspend or unsplit before split.

1. `split()`, `suspend()`, or `stop()` cannot be invoked twice
2. `unsplit()` may only be called if the watch has been `split()`
3. `resume()` may only be called if the watch has been `suspend()`
4. `start()` cannot be called twice without calling `reset()`

This class is not thread-safe.

Since:
  2.0
See Also:
  - `DurationUtils.of(FailableRunnable)`
  - `DurationUtils.of(FailableConsumer)`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `StopWatch.Split`
  Stores a split as a label and duration.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `StopWatch()`
  Constructs a new instance.
  `StopWatch(String message)`
  Constructs a new instance.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static StopWatch`
  `create()`
  Creates a StopWatch.
  `static StopWatch`
  `createStarted()`
  Creates and starts a StopWatch.
  `String`
  `formatSplitTime()`
  Formats the split time with `DurationFormatUtils.formatDurationHMS(long)`.
  `String`
  `formatTime()`
  Formats the time formatted with `DurationFormatUtils.formatDurationHMS(long)`.
  `<T> T`
  `get(Supplier<T> supplier)`
  Delegates to `Supplier.get()` while recording the duration of the call.
  `Duration`
  `getDuration()`
  Gets the Duration on this StopWatch.
  `String`
  `getMessage()`
  Gets the message for string presentation.
  `long`
  `getNanoTime()`
  Gets the elapsed time in nanoseconds.
  `Duration`
  `getSplitDuration()`
  Gets the split Duration on this StopWatch.
  `long`
  `getSplitNanoTime()`
  Gets the split time in nanoseconds.
  `List<StopWatch.Split>`
  `getSplits()`
  Gets the split list.
  `long`
  `getSplitTime()`
  Deprecated.
  Use `getSplitDuration()`.
  `Instant`
  `getStartInstant()`
  Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
  `long`
  `getStartTime()`
  Deprecated.
  Use `getStartInstant()`.
  `Instant`
  `getStopInstant()`
  Gets the Instant this StopWatch was stopped, between the current time and midnight, January 1, 1970 UTC.
  `long`
  `getStopTime()`
  Deprecated.
  Use `getStopInstant()`.
  `<T, E extends Throwable>
  T`
  `getT(FailableSupplier<T,E> supplier)`
  Delegates to `FailableSupplier.get()` while recording the duration of the call.
  `long`
  `getTime()`
  Gets the time on this StopWatch.
  `long`
  `getTime(TimeUnit timeUnit)`
  Gets the time in the specified TimeUnit.
  `boolean`
  `isStarted()`
  Tests whether this StopWatch is started.
  `boolean`
  `isStopped()`
  Tests whether StopWatch is stopped. this StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.
  `boolean`
  `isSuspended()`
  Tests whether this StopWatch is suspended.
  `void`
  `reset()`
  Resets this StopWatch.
  `void`
  `resume()`
  Resumes this StopWatch after a suspend.
  `void`
  `run(Runnable runnable)`
  Delegates to `Runnable.run()` while recording the duration of the call.
  `<E extends Throwable>
  void`
  `runT(FailableRunnable<E> runnable)`
  Delegates to `FailableRunnable.run()` while recording the duration of the call.
  `void`
  `split()`
  Splits the time.
  `void`
  `split(String label)`
  Splits the time with a label.
  `void`
  `start()`
  Starts this StopWatch.
  `void`
  `stop()`
  Stops this StopWatch.
  `void`
  `suspend()`
  Suspends this StopWatch for later resumption.
  `String`
  `toSplitString()`
  Gets a summary of the last split time that this StopWatch recorded as a string.
  `String`
  `toString()`
  Gets a summary of the time that this StopWatch recorded as a string.
  `void`
  `unsplit()`
  Removes the split.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### StopWatch

    public StopWatch()
    Constructs a new instance.

  - ### StopWatch

    public StopWatch(String message)
    Constructs a new instance.
    Parameters:
      `message` - A message for string presentation.
    Since:
      3.10

- ## Method Details

  - ### create

    public static StopWatch create()
    Creates a StopWatch.
    Returns:
      StopWatch a StopWatch.
    Since:
      3.10

  - ### createStarted

    public static StopWatch createStarted()
    Creates and starts a StopWatch.
    Returns:
      StopWatch a started StopWatch.
    Since:
      3.5

  - ### formatSplitTime

    public String formatSplitTime()
    Formats the split time with `DurationFormatUtils.formatDurationHMS(long)`.
    Returns:
      the split time formatted by `DurationFormatUtils.formatDurationHMS(long)`.
    Since:
      3.10

  - ### formatTime

    public String formatTime()
    Formats the time formatted with `DurationFormatUtils.formatDurationHMS(long)`.
    Returns:
      the time formatted by `DurationFormatUtils.formatDurationHMS(long)`.
    Since:
      3.10

  - ### get

    public <T> T get(Supplier<T> supplier)
    Delegates to `Supplier.get()` while recording the duration of the call.
    Type Parameters:
      `T` - the type of results supplied by this supplier.
    Parameters:
      `supplier` - The supplier to `Supplier.get()`.
    Returns:
      a result from the given Supplier.
    Since:
      3.18.0

  - ### getDuration

    public Duration getDuration()
    Gets the Duration on this StopWatch.

    This is either the Duration between the start and the moment this method is called, or the Duration between start and stop.

    Returns:
      the Duration.
    Since:
      3.16.0

  - ### getMessage

    public String getMessage()
    Gets the message for string presentation.
    Returns:
      the message for string presentation.
    Since:
      3.10

  - ### getSplits

    public List<StopWatch.Split> getSplits()
    Gets the split list.
    Returns:
      the list of splits.
    Since:
      3.20.0

  - ### getNanoTime

    public long getNanoTime()
    Gets the elapsed time in nanoseconds.

    This is either the time between the start and the moment this method is called, or the amount of time between start and stop.

    Returns:
      the elapsed time in nanoseconds.
    Since:
      3.0
    See Also:
      - `System.nanoTime()`

  - ### getSplitDuration

    public Duration getSplitDuration()
    Gets the split Duration on this StopWatch.

    This is the Duration between start and latest split.

    Returns:
      the split Duration.
    Throws:
      `IllegalStateException` - if this StopWatch has not yet been split.
    Since:
      3.16.0

  - ### getSplitNanoTime

    public long getSplitNanoTime()
    Gets the split time in nanoseconds.

    This is the time between start and latest split.

    Returns:
      the split time in nanoseconds.
    Throws:
      `IllegalStateException` - if this StopWatch has not yet been split.
    Since:
      3.0

  - ### getSplitTime

    @Deprecated public long getSplitTime()
    Deprecated.
    Use `getSplitDuration()`.
    Gets the split time on this StopWatch.

    This is the time between start and latest split.

    Returns:
      the split time in milliseconds.
    Throws:
      `IllegalStateException` - if this StopWatch has not yet been split.
    Since:
      2.1

  - ### getStartInstant

    public Instant getStartInstant()
    Gets the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
    Returns:
      the Instant this StopWatch was started, between the current time and midnight, January 1, 1970 UTC.
    Throws:
      `IllegalStateException` - if this StopWatch has not been started.
    Since:
      3.16.0

  - ### getStartTime

    @Deprecated public long getStartTime()
    Deprecated.
    Use `getStartInstant()`.
    Gets the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
    Returns:
      the time this StopWatch was started in milliseconds, between the current time and midnight, January 1, 1970 UTC.
    Throws:
      `IllegalStateException` - if this StopWatch has not been started.
    Since:
      2.4

  - ### getStopInstant

    public Instant getStopInstant()
    Gets the Instant this StopWatch was stopped, between the current time and midnight, January 1, 1970 UTC.
    Returns:
      the Instant this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
    Throws:
      `IllegalStateException` - if this StopWatch has not been started.
    Since:
      3.16.0

  - ### getStopTime

    @Deprecated public long getStopTime()
    Deprecated.
    Use `getStopInstant()`.
    Gets the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
    Returns:
      the time this StopWatch was stopped in milliseconds, between the current time and midnight, January 1, 1970 UTC.
    Throws:
      `IllegalStateException` - if this StopWatch has not been started.
    Since:
      3.12.0

  - ### getT

    public <T, E extends Throwable> T getT(FailableSupplier<T,E> supplier) throws Throwable
    Delegates to `FailableSupplier.get()` while recording the duration of the call.
    Type Parameters:
      `T` - the type of results supplied by this supplier.
      `E` - The kind of thrown exception or error.
    Parameters:
      `supplier` - The supplier to `Supplier.get()`.
    Returns:
      a result from the given Supplier.
    Throws:
      `Throwable` - if the supplier fails.
    Since:
      3.18.0

  - ### getTime

    public long getTime()
    Gets the time on this StopWatch.

    This is either the time between the start and the moment this method is called, or the amount of time between start and stop.

    Returns:
      the time in milliseconds.
    See Also:
      - `getDuration()`

  - ### getTime

    public long getTime(TimeUnit timeUnit)
    Gets the time in the specified TimeUnit.

    This is either the time between the start and the moment this method is called, or the amount of time between start and stop. The resulting time will be expressed in the desired TimeUnit with any remainder rounded down. For example, if the specified unit is `TimeUnit.HOURS` and this StopWatch time is 59 minutes, then the result returned will be `0`.

    Parameters:
      `timeUnit` - the unit of time, not null.
    Returns:
      the time in the specified TimeUnit, rounded down.
    Since:
      3.5

  - ### isStarted

    public boolean isStarted()
    Tests whether this StopWatch is started. A suspended StopWatch is also started watch.
    Returns:
      boolean If this StopWatch is started.
    Since:
      3.2

  - ### isStopped

    public boolean isStopped()
    Tests whether StopWatch is stopped. this StopWatch which's not yet started and explicitly stopped StopWatch is considered as stopped.
    Returns:
      boolean If this StopWatch is stopped.
    Since:
      3.2

  - ### isSuspended

    public boolean isSuspended()
    Tests whether this StopWatch is suspended.
    Returns:
      boolean If this StopWatch is suspended.
    Since:
      3.2

  - ### reset

    public void reset()
    Resets this StopWatch. Stops it if need be.

    This method clears the internal values to allow the object to be reused.

  - ### resume

    public void resume()
    Resumes this StopWatch after a suspend.

    This method resumes the watch after it was suspended. The watch will not include time between the suspend and resume calls in the total time.

    Throws:
      `IllegalStateException` - if this StopWatch has not been suspended.

  - ### run

    public void run(Runnable runnable)
    Delegates to `Runnable.run()` while recording the duration of the call.
    Parameters:
      `runnable` - The runnable to `Runnable.run()`.
    Since:
      3.18.0

  - ### runT

    public <E extends Throwable> void runT(FailableRunnable<E> runnable) throws Throwable
    Delegates to `FailableRunnable.run()` while recording the duration of the call.
    Type Parameters:
      `E` - The kind of `Throwable`.
    Parameters:
      `runnable` - The runnable to `FailableRunnable.run()`.
    Throws:
      `Throwable` - Thrown by `FailableRunnable.run()`.
    Since:
      3.18.0

  - ### split

    public void split()
    Splits the time.

    This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling `unsplit()` to continue the timing from the original start point.

    Throws:
      `IllegalStateException` - if this StopWatch is not running.

  - ### split

    public void split(String label)
    Splits the time with a label.

    This method sets the stop time of the watch to allow a time to be extracted. The start time is unaffected, enabling `unsplit()` to continue the timing from the original start point.

    Parameters:
      `label` - A message for string presentation.
    Throws:
      `IllegalStateException` - if the StopWatch is not running.
    Since:
      3.20.0

  - ### start

    public void start()
    Starts this StopWatch.

    This method starts a new timing session, clearing any previous values.

    Throws:
      `IllegalStateException` - if this StopWatch is already running.

  - ### stop

    public void stop()
    Stops this StopWatch.

    This method ends a new timing session, allowing the time to be retrieved.

    Throws:
      `IllegalStateException` - if this StopWatch is not running.

  - ### suspend

    public void suspend()
    Suspends this StopWatch for later resumption.

    This method suspends the watch until it is resumed. The watch will not include time between the suspend and resume calls in the total time.

    Throws:
      `IllegalStateException` - if this StopWatch is not currently running.

  - ### toSplitString

    public String toSplitString()
    Gets a summary of the last split time that this StopWatch recorded as a string.

    The format used is ISO 8601-like, [message ]hours:minutes:seconds.milliseconds.

    Returns:
      the split time as a String.
    Since:
      2.1, 3.10 Returns the prefix `"message "` if the message is set.

  - ### toString

    public String toString()
    Gets a summary of the time that this StopWatch recorded as a string.

    The format used is ISO 8601-like, [message ]hours:minutes:seconds.milliseconds.

    Overrides:
      `toString` in class `Object`
    Returns:
      the time as a String.
    Since:
      3.10 Returns the prefix `"message "` if the message is set.

  - ### unsplit

    public void unsplit()
    Removes the split.

    This method clears the stop time. The start time is unaffected, enabling timing from the original start point to continue.

    Throws:
      `IllegalStateException` - if this StopWatch has not been split.