Package ca.corbett.extras.logging

Class Stopwatch

java.lang.Object
ca.corbett.extras.logging.Stopwatch
public abstract class Stopwatch extends Object
Provides static utility methods for tracking how long operations take, for logging and diagnostic purposes.

Starting timers

You can have as many timers running simultaneously as you wish, memory permitting. Each time you invoke Stopwatch.start() with a unique timer string id, a new timer is added. If you invoke Stopwatch.start() with the id of a timer that is already in progress, that timer is restarted and its previous value is lost.

Monitoring timers in progress

You can report on the status of a running timer without stopping it by invoking the report() or reportFormatted() method. You can check to see if a timer is currently running using the isRunning() method, and you can see how many timers are currently running via the getTimerCount() method.

Stopping a timer

Calling Stopwatch.stop() will stop a timer and mark how much time it counted while it was running. At any point after stopping a timer, you can invoke report() or reportFormatted() to get this information. A stopped timer can be restarted by passing its id to the start() method.

Formatting timing information

The raw timer results can be retrieved by report(), which simply returns the number of milliseconds for which the timer in question ran. If you want a more human-readable version of this information, you can invoke reportFormatted() and get a friendlier string version, along the lines of "1h24m32s". Note that fractional second values are ignored by reportFormatted(). If higher precision is required, use the report() method instead.

Since:
2023-03-17
Author:
scorbo2

  • Constructor Summary

    Constructors
    Constructor
    Description
    Stopwatch()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    formatTimeValue(long timeValue)
    Takes a count of milliseconds and returns it in a human-readable format along the lines of "1h24m32s".
    static int
    getTimerCount()
    Returns a count of how many timers are currently running.
    static boolean
    isRunning(String id)
    Indicates whether a timer with the given id is currently running.
    static long
    report(String id)
    Reports on the timer with the given identifier.
    static String
    reportFormatted(String id)
    Reports on the timer with the given identifier.
    static void
    start(String id)
    Starts a timer with the given identifier.
    static long
    stop(String id)
    Stops the timer with the given identifier, and notes the count of milliseconds for which that timer was running.
    static int
    stopAll()
    Stops all timers, and returns a count of how many timers were affected.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Stopwatch

      public Stopwatch()

  • Method Details

    • start

      public static void start(String id)
      Starts a timer with the given identifier. If a timer with that identifier is already running, it is restarted.
      Parameters:
      id - Any String which uniquely identifies this timer. Null values are ignored.

    • stop

      public static long stop(String id)
      Stops the timer with the given identifier, and notes the count of milliseconds for which that timer was running. The elapsed time in milliseconds is returned from this method, but can also be queried via the report methods. If the given id does not reference a currently running timer, this method does nothing and will return 0.
      Parameters:
      id - The unique String identifier of the timer in question.
      Returns:
      The number of milliseconds for which the timer in question was running.

    • stopAll

      public static int stopAll()
      Stops all timers, and returns a count of how many timers were affected.
      Returns:
      How many timers were stopped by this call.

    • getTimerCount

      public static int getTimerCount()
      Returns a count of how many timers are currently running.
      Returns:
      How many timers are currently running.

    • isRunning

      public static boolean isRunning(String id)
      Indicates whether a timer with the given id is currently running.
      Parameters:
      id - The identifier of the timer in question.
      Returns:
      true if the named timer exists and is running.

    • report

      public static long report(String id)
      Reports on the timer with the given identifier. If the identifier refers to a timer that is currently running, then the return value is the number of milliseconds for which the timer in question has been running. The timer will not be stopped as a result of this call. If the identifier refers to a timer that has been stopped, then the result is the number of milliseconds for which that timer ran before it was stopped. If the given identifier does not match any known timer, then this method does nothing and will return 0.
      Parameters:
      id - The identifier of the timer in question.
      Returns:
      A count of milliseconds for the given timer, as described above.

    • reportFormatted

      public static String reportFormatted(String id)
      Reports on the timer with the given identifier. This is similar to the report method except that the return value here is a formatted, human-readable string describing the elapsed time. For example: "1m24s" instead of 84000.
      Parameters:
      id - The identifier of the timer in question.
      Returns:
      A human-readable string representing the elapsed time.

    • formatTimeValue

      public static String formatTimeValue(long timeValue)
      Takes a count of milliseconds and returns it in a human-readable format along the lines of "1h24m32s". Extremely short values (less than one second) are returned in the format "44ms".
      Parameters:
      timeValue - An arbitrary millisecond count.
      Returns:
      A formatted String that describes how long the given timeValue is.