Package net.obvj.performetrics

Class Stopwatch

  • public class Stopwatch
extends TimingSessionContainer

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

      • 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