initial commit

timer/com/vladium/utils/timing/ITimer.java

@@ -0,0 +1,54 @@
+
+package com.vladium.utils.timing;
+
+// ----------------------------------------------------------------------------
+/**
+ * A simple interface for measuring time intervals. An instance of this goes
+ * through the following lifecycle states:
+ * <DL>
+ *  <DT> <EM>ready</EM>
+ *      <DD> timer is ready to start a new measurement
+ *  <DT> <EM>started</EM>
+ *      <DD> timer has recorded the starting time interval point
+ *  <DT> <EM>stopped</EM>
+ *      <DD> timer has recorded the ending time interval point
+ * </DL>
+ * See individual methods for details.<P>
+ * 
+ * If this library has been compiled with {@link ITimerConstants#DO_STATE_CHECKS}
+ * set to 'true' the implementation will enforce this lifecycle model and throw
+ * IllegalStateException when it is violated.
+ * 
+ * @author (C) <a href="mailto:vroubtsov@illinoisalumni.org">Vlad Roubtsov</a>, 2002
+ */
+public interface ITimer
+{
+    // public: ................................................................
+    
+    /**
+     * Starts a new time interval and advances this timer instance to 'started'
+     * state. This method can be called from 'ready' state only.
+     */
+    void start ();
+    
+    /**
+     * Terminates the current time interval and advances this timer instance to
+     * 'stopped' state. Interval duration will be available via
+     * {@link #getDuration()} method. This method can be called from 'started'
+     * state only. 
+     */
+    void stop ();
+    
+    /**
+     * Returns the duration of the time interval that elapsed between the last
+     * calls to {@link #start()} and {@link #stop()}. This method can be called
+     * any number of times from 'stopped' state and will return the same value
+     * each time.<P>
+     * 
+     * @return interval duration in milliseconds 
+     */
+    double getDuration ();
+    
+    /**
+     * This method can be called from any state and will reset this timer
+     * instance back to 'ready' state. 

timer/com/vladium/utils/timing/ITimerConstants.java

@@ -0,0 +1,31 @@
+
+package com.vladium.utils.timing;
+
+// ----------------------------------------------------------------------------
+/**
+ * A package-private collection of constants used by {@link ITimer} implementations
+ * in <code>HRTimer</code> and <code>JavaSystemTimer</code> classes.
+ *
+ * @author (C) <a href="mailto:vroubtsov@illinoisalumni.org">Vlad Roubtsov</a>, 2002
+ */
+interface ITimerConstants
+{
+    // public: ................................................................
+    
+    /**
+     * Conditional compilation flag to enable/disable state checking in timer
+     * implementations. Just about the only reason you might want to disable
+     * this is to reduce the timer overhead, but in practice the gain is very
+     * small. 
+     */
+    static final boolean DO_STATE_CHECKS = true;
+    
+    /**
+     * Timer state enumeration. 
+     */
+    static final int STATE_READY = 0, STATE_STARTED = 1, STATE_STOPPED = 2;
+    
+    /**
+     * User-friendly timer state names indexed by their state values.
+     */
+    static final String [] STATE_NAMES = {"READY", "STARTED", "STOPPED"};

timer/com/vladium/utils/timing/JavaSystemTimer.java

@@ -0,0 +1,74 @@
+
+package com.vladium.utils.timing;
+
+// ----------------------------------------------------------------------------
+/**
+ * A package-private implementation of {@link ITimer} based around Java system
+ * timer [<code>System.currentTimeMillis()</code> method]. It is used when
+ * <code>HRTimer</code> implementation is unavailable.<P> 
+ * 
+ * {@link TimerFactory} acts as the Factory for this class.<P>
+ * 
+ * MT-safety: an instance of this class is safe to be used within the same
+ * thread only.
+ * 
+ * @author (C) <a href="mailto:vroubtsov@illinoisalumni.org">Vlad Roubtsov</a>, 2002
+ */
+final class JavaSystemTimer implements ITimer, ITimerConstants 
+{
+    // public: ................................................................
+    
+    public void start ()
+    {
+        if (DO_STATE_CHECKS)
+        {
+            if (m_state != STATE_READY)
+                throw new IllegalStateException (this + ": start() must be called from READY state, current state is " + STATE_NAMES [m_state]);
+        }
+        
+        if (DO_STATE_CHECKS) m_state = STATE_STARTED;
+        m_data = System.currentTimeMillis ();
+    }
+    
+    public void stop ()
+    {
+        // latch stop time in a local var before doing anything else:
+        final long data = System.currentTimeMillis ();
+        
+        if (DO_STATE_CHECKS)
+        {
+            if (m_state != STATE_STARTED)
+                throw new IllegalStateException (this + ": stop() must be called from STARTED state, current state is " + STATE_NAMES [m_state]);
+        }
+        
+        m_data = data - m_data;
+        if (DO_STATE_CHECKS) m_state = STATE_STOPPED;
+    }
+    
+    public double getDuration ()
+    {
+        if (DO_STATE_CHECKS)
+        {
+            if (m_state != STATE_STOPPED)
+                throw new IllegalStateException (this + ": getDuration() must be called from STOPPED state, current state is " + STATE_NAMES [m_state]);
+        }
+        
+        return m_data;
+    }
+    
+    public void reset ()
+    {
+        if (DO_STATE_CHECKS) m_state = STATE_READY;
+    }
+    
+    // protected: .............................................................
+
+    // package: ...............................................................
+        
+    // private: ...............................................................
+    
+    private int m_state; // used to keep track of timer state
+    private long m_data; // timing data
+
+} // end of class
+// ----------------------------------------------------------------------------

timer/com/vladium/utils/timing/TimerFactory.java

@@ -0,0 +1,74 @@
+
+package com.vladium.utils.timing;
+
+// ----------------------------------------------------------------------------
+/**
+ * This non-instantiable non-extendible class acts as a Factory for {@link ITimer}
+ * implementations.
+ * 
+ * @author (C) <a href="mailto:vroubtsov@illinoisalumni.org">Vlad Roubtsov</a>, 2002
+ */
+public abstract class TimerFactory
+{
+    // public: ................................................................
+
+	private static final String HRTIMER_LIB = "hrtlib";
+
+    /**
+     * Creates a new instance of {@link ITimer} which is returned in 'ready'
+     * state. If the JNI-based/high-resolution implementation is not available
+     * this will return an instance of <code>JavaSystemTimer</code>, so this
+     * method is guaranteed not to fail.
+     * 
+     * @return ITimer a new timer instance in 'ready' state [never null] 
+     */
+	
+	public static void initialize(String path) {
+
+		UnsatisfiedLinkError exception = null;
+		
+		try {
+			System.loadLibrary (HRTIMER_LIB);
+		} catch (UnsatisfiedLinkError e) {
+			if(path != null) {
+				try {
+					System.load(path);
+				} catch (UnsatisfiedLinkError ex) {
+					exception = ex;
+				}
+			} else {
+				exception = e;
+			}
+		}
+
+		if(exception != null) {
+			System.out.println ("native lib '" + HRTIMER_LIB
+					+ "' not found in 'java.library.path': "
+					+ System.getProperty ("java.library.path")
+					+path==null?"":(" or in "+path));
+
+			throw exception; // re-throw
+		}
+	}
+	
+    public static ITimer newTimer ()
+    {
+//        try
+//        {
+            return new HRTimer ();
+//        }
+//        catch (Throwable t)
+//        {
+//            return new JavaSystemTimer ();
+//        }
+    }
+    
+    // protected: .............................................................
+
+    // package: ...............................................................
+    
+    // private: ...............................................................
+    
+    private TimerFactory () {} // prevent subclassing
+    
+} // end of class