Package com.complexible.common.timer

Class Timer

  • public class Timer
extends java.lang.Object

    Class used to keep track how much time is spent for a specific operation. Timers are primarily used to display info about performance. A timer is started at the beginning of a function and is stopped at the end of that function (special care needed when there are multiple return commands in a function because the status of unstopped timers is undefined). A timer also stores how many times the timer has been started so average time spent in a function can be computed.

    When a timer is used in a recursive function it will typically be started multiple times. Timer class will only measure the time spent in the first call. This is done by counting how many times a timer is started and time spent is computed only when the number of stop() calls evens out the start() calls. It is the programmer's responsibility to make sure each start() is stopped by a stop() call.

    Each timer may be associated with a timeout limit. This means that time spent between start() and stop() calls should be less than the timeout specified. Timeouts will only be checked when check() function is called. If check() function is not called setting timeouts has no effect. It is up to the programmer to decide when and how many times a timer will be checked.

    There may be a dependency between timers. For example, classification, realization and entailment operations all use consistency checks. If something goes wrong inside a consistency check and that operation does not finish in a reasonable time, the timeout on the parent timer may expire. To handle such cases, a timer may be associated with a parent timer so every time a timer is checked for a timeout, its parent timer will also be checked. Normally, we would like to associate many parents with a timer but for efficiency reasons (looping over an array each time is expensive) each timer is allowed to have only one parent.

    Timers class stores a set of timers and provides functions to start, stop and check timers.

    Since:
    2.0
    Version:
    2.0
    Author:
    Evren Sirin
    See Also:
    Timers

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static long NO_TIMEOUT  
      static long NOT_STARTED  

    • Constructor Summary

      Constructors 
      Constructor Description
      Timer()
      Create a timer with no name and no parent.
      Timer​(java.lang.String name)
      Create a timer with no parent.
      Timer​(java.lang.String name, Timer parent)
      Create a timer that has the specified parent timer.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(Timer timer)
      Update the total time elapsed and number of counts by by adding the values from another timer.
      void check()
      Check if the elapsed time is greater than the timeout limit and throw a TimeoutException if that is the case.
      java.lang.String format()  
      double getAverage()
      Return the total time spent (in milliseconds) divided by the number of times this timer has been ran.
      long getCount()
      Return the total number of times this timer has been started and stopped.
      long getElapsed()
      Return the time elapsed (in milliseconds) since the last time this timer was started.
      long getLast()
      Return the total time spent between last start()-stop() period.
      java.lang.String getName()
      Return the name of this timer.
      Timer getParent()
      Return the parent timer of this timer depends on.
      long getTimeout()
      Return the timeout associated with this timer.
      long getTotal()
      Return the total time (in milliseconds) spent while this timer was running.
      void interrupt()
      Interrupt timer so that the next check() call will throw an InterruptedException
      boolean isStarted()
      Return true if timer has been started with a start() call but not has been stopped with a stop() call.
      void reset()
      Reset all the internal counts associated with this timer.
      void restart()
      If started stop the timer and then start it again.
      void setTimeout​(long timeout)
      Set a timeout limit for this timer.
      void start()
      Start time timer by recording the time this function is called.
      long stop()
      Stop the timer, increment the count and update the total time spent.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Timer

        public Timer()
        Create a timer with no name and no parent.

      • Timer

        public Timer​(java.lang.String name)
        Create a timer with no parent.
        Parameters:
        name -

      • Timer

        public Timer​(java.lang.String name,
             Timer parent)
        Create a timer that has the specified parent timer.
        Parameters:
        name -
        parent -

    • Method Detail

      • add

        public void add​(Timer timer)
        Update the total time elapsed and number of counts by by adding the values from another timer. This is especially useful if we are running
        Parameters:
        timer -

      • start

        public void start()
        Start time timer by recording the time this function is called. If timer is running when this function is called time is not recorded and only an internal counter is updated.

      • stop

        public long stop()
        Stop the timer, increment the count and update the total time spent. If timer has been started multiple times this function will only decrement the internal counter. Time information is updated only when all starts are evened out by stops.
        Returns:
        Return the total time spent after last start(), -1 if timer is still running, -Long.MAX_VALUE on error

      • reset

        public void reset()
        Reset all the internal counts associated with this timer. After this function call it will be like timer has never been used.

      • restart

        public void restart()
        If started stop the timer and then start it again.

      • check

        public void check()
        Check if the elapsed time is greater than the timeout limit and throw a TimeoutException if that is the case. Check the parent timer if there is one.

      • interrupt

        public void interrupt()
        Interrupt timer so that the next check() call will throw an InterruptedException

      • isStarted

        public boolean isStarted()
        Return true if timer has been started with a start() call but not has been stopped with a stop() call.
        Returns:

      • getName

        public java.lang.String getName()
        Return the name of this timer.
        Returns:

      • getElapsed

        public long getElapsed()
        Return the time elapsed (in milliseconds) since the last time this timer was started. If the timer is not running now 0 is returned.
        Returns:

      • getTotal

        public long getTotal()
        Return the total time (in milliseconds) spent while this timer was running. If the timer is running when this function is called time elapsed will be discarded. Therefore, it is advised to use this function only with stopped timers.
        Returns:

      • getCount

        public long getCount()
        Return the total number of times this timer has been started and stopped. Note that recursive start operations are computed only once so actual number of times start() function is called may be greater than this amount.
        Returns:

      • getTimeout

        public long getTimeout()
        Return the timeout associated with this timer.
        Returns:

      • getAverage

        public double getAverage()
        Return the total time spent (in milliseconds) divided by the number of times this timer has been ran. If the timer is still running elapsed time is discarded. Therefore, it is advised to use this function only with stopped timers.
        Returns:

      • getLast

        public long getLast()
        Return the total time spent between last start()-stop() period.
        Returns:

      • setTimeout

        public void setTimeout​(long timeout)
        Set a timeout limit for this timer. Set the timeout to 0 to disable timeout checking
        Parameters:
        timeout -

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getParent

        public Timer getParent()
        Return the parent timer of this timer depends on. Parent timers are checked hierarchically for timeouts.
        Returns:
        Parent timer or null if there is no such timer.

      • format

        public java.lang.String format()