Package net.obvj.performetrics

Class TimingSession

  • Direct Known Subclasses:
    UnmodifiableTimingSession
    public class TimingSession
extends Object

    A convenient timing object that supports multiple counter types.

    Use the default constructor, with no arguments, to create a timing session with all of the available metrics. If required, an additional constructor may be used to provide a timing session with specific counters. E.g.: 

     new TimingSession(); // provides all available counter types
 new TimingSession(Counter.Type.WALL_CLOCK_TIME); // wall-clock time only
 new TimingSession(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.

    Use elapsedTime(Counter.Type) to retrieve the elapsed time for a particular counter. E.g.: 

     double elapsedTimeNanos = cpuTime.elapsedTime(Counter.Type.CPU_TIME, TimeUnit.NANOSECONDS);

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

    Since:
    2.2.0
    Author:
    oswaldo.bapvic.jr
    See Also:
    Counter, Counter.Type, Stopwatch

    • Constructor Detail

      • TimingSession

        public TimingSession​(List<Counter.Type> types)
        Creates a new timing session with custom counter types.
        Parameters:
        types - the counter types to set

    • Method Detail

      • reset

        public void reset()
        Resets all counters associated with this timing session.

      • start

        public void start()
        Starts the timing session.
        Throws:
        IllegalStateException - if the session state is not suitable for this action

      • stop

        public void stop()
        Stops the timing session.
        Throws:
        IllegalStateException - if the session state is not suitable for this action

      • isStarted

        public boolean isStarted()
        Returns true if this timing session is started.
        Returns:
        true if the timing session is started; otherwise, false

      • elapsedTime

        public Duration elapsedTime​(Counter.Type type)
        A convenient method that returns the elapsed time of a specific counter.

        This has the same effect as calling: timingSession.getCounter(type).elapsedTime()

        Parameters:
        type - the counter type to be fetched
        Returns:
        the elapsed time for the specified counter
        Throws:
        IllegalArgumentException - if the type was not specified in this timing session
        Since:
        2.1.0

      • elapsedTime

        public double elapsedTime​(Counter.Type type,
                          TimeUnit timeUnit)
        A convenient method that returns the elapsed time of a specific counter, in the specified time unit.

        This has the same effect as calling: timingSession.getCounter(type).elapsedTime(timeUnit)

        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 using the default conversion mode.
        Throws:
        IllegalArgumentException - if the type was not specified in this timing session
        Since:
        2.1.0

      • elapsedTime

        public double elapsedTime​(Counter.Type type,
                          TimeUnit timeUnit,
                          ConversionMode conversionMode)
        A convenient method that returns the elapsed time of a specific counter, in the specified time unit, by applying a custom ConversionMode.

        This has the same effect as calling: timingSession.getCounter(type).elapsedTime(timeUnit, conversionMode)

        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 using the given conversion mode.
        Throws:
        IllegalArgumentException - if the type was not specified in this timing session
        Since:
        2.1.0