Package org.apache.commons.lang3.time

Class StopWatch

  • public class StopWatch
extends java.lang.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)

    • Field Detail

      • message

        private final java.lang.String message
        A message for string presentation.
        Since:
        3.10

      • runningState

        private StopWatch.State runningState
        The current running state of this StopWatch.

      • splitState

        private StopWatch.SplitState splitState
        Whether this StopWatch has a split time recorded.

      • startTimeNanos

        private long startTimeNanos
        The start time in nanoseconds. This field can be removed once we move off of Java 8.

      • startInstant

        private java.time.Instant startInstant
        The start Instant.

        nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.

        On Java 8, Instant has millisecond precision, later versions use nanoseconds.

      • stopInstant

        private java.time.Instant stopInstant
        The end Instant.

        nanoTime is only for elapsed time so we need to also store the currentTimeMillis to maintain the old getStartTime API.

        On Java 8, Instant has millisecond precision, later versions use nanoseconds.

      • stopTimeNanos

        private long stopTimeNanos
        The stop time in nanoseconds. This field can be removed once we move off of Java 8.

    • Constructor Detail

      • StopWatch

        public StopWatch()
        Constructs a new instance.

      • StopWatch

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

    • Method Detail

      • 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

      • get

        public <T> T get​(java.util.function.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 java.time.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 java.lang.String getMessage()
        Gets the message for string presentation.
        Returns:
        the message for string presentation.
        Since:
        3.10

      • 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 java.time.Duration getSplitDuration()
        Gets the split Duration on this StopWatch.

        This is the Duration between start and latest split.

        Returns:
        the split Duration
        Throws:
        java.lang.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:
        java.lang.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:
        java.lang.IllegalStateException - if this StopWatch has not yet been split.
        Since:
        2.1

      • getStartInstant

        public java.time.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:
        java.lang.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:
        java.lang.IllegalStateException - if this StopWatch has not been started
        Since:
        2.4

      • getStopInstant

        public java.time.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:
        java.lang.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:
        java.lang.IllegalStateException - if this StopWatch has not been started
        Since:
        3.12.0

      • getT

        public <T,​E extends java.lang.Throwable> T getT​(FailableSupplier<T,​E> supplier)
                                               throws java.lang.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:
        java.lang.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​(java.util.concurrent.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

      • nanosToMillis

        private long nanosToMillis​(long nanos)
        Converts nanoseconds to milliseconds.
        Parameters:
        nanos - nanoseconds to convert.
        Returns:
        milliseconds conversion result.

      • 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:
        java.lang.IllegalStateException - if this StopWatch has not been suspended.

      • run

        public void run​(java.lang.Runnable runnable)
        Delegates to Runnable.run() while recording the duration of the call.
        Parameters:
        runnable - The runnable to Runnable.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:
        java.lang.IllegalStateException - if this StopWatch is not running.

      • start

        public void start()
        Starts this StopWatch.

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

        Throws:
        java.lang.IllegalStateException - if this StopWatch is already running.

      • startResume

        private void startResume()
        Starts or resumes this StopWatch.

      • stop

        public void stop()
        Stops this StopWatch.

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

        Throws:
        java.lang.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:
        java.lang.IllegalStateException - if this StopWatch is not currently running.

      • toSplitString

        public java.lang.String toSplitString()
        Gets a summary of the 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 java.lang.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 java.lang.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:
        java.lang.IllegalStateException - if this StopWatch has not been split.