001 // Clock.java, created by cata
002 // Copyright (C) 2001 Catalin Francu <cata@mit.edu>
003 // Licensed under the terms of the GNU GPL; see COPYING for details.
004
005 package javax.realtime;
006
007 /** A clock advances from the past, through the present, into the future.
008 * It has a concept of now that can be queried through
009 * <code>Clock.getTime()</code>, and it can have events queued on it
010 * which will be fired when their appointed time is reached. There are
011 * many possible subclasses of clocks: real-time clocks, user time
012 * clocks, simulation time clocks. The idea of using multiple clocks
013 * may at first seem unusual but we allow it as a possible resource
014 * allocation strategy. Consider a real-time system where the natural
015 * events of the system have different tolerances for jitter (jitter
016 * refers to the distribution of the differences between when the
017 * events are actually raised or noticed by the software and when they
018 * should have really occurred according to time in the real-world).
019 * Assume the system functions properly if event A is noticed or raised
020 * within plus or minus 100 seconds of the actual time it should occur
021 * but event B must be noticed or raised within 100 microseconds of its
022 * actual time. Further assume, without loss of generality, that events
023 * A and B are periodic. An application could then create two instances
024 * of <code>PeriodicTimer</code> based on two clocks. The timer for
025 * event B should be based on a Clock which checks its queue at least
026 * every 100 microseconds but the timer for event A could be based on a
027 * Clock that checked its queue only every 100 seconds. This use of two
028 * clocks reduces the queue size of the accurate clock and thus queue
029 * management overhead is reduced.
030 */
031 public abstract class Clock {
032
033 private RelativeTime resolution;
034 private static RealtimeClock rtc = null;
035
036 /** Constructor for the abstract class. */
037 public Clock() {}
038
039 /** There is always one clock object available: a realtime clock that advances
040 * in sync with the external world. This is the default <code>Clock</code>.
041 *
042 * @return An instance of the default <code>Clock</code>.
043 */
044 public static Clock getRealtimeClock() {
045 if (rtc == null) rtc = new RealtimeClock();
046 return rtc;
047 }
048
049 /** Gets the resolution of the clock -- the interval between ticks.
050 *
051 * @return An instance of <code>RelativeTime</code> representing the
052 * resolution of <code>this</code>.
053 */
054 public abstract RelativeTime getResolution();
055
056 /** Gets the current time in a freshly allocated object.
057 *
058 * @return An instance of <code>AbsoluteTime</code> representing the
059 * current time.
060 */
061 public AbsoluteTime getTime() {
062 AbsoluteTime time = new AbsoluteTime();
063 getTime(time);
064 return time;
065 }
066
067 /** Gets the current time in an existing object. The time represented
068 * by the given <code>AbsoluteTime</code> is changed some time between
069 * the invocation of the method and the return of the method.
070 *
071 * @param time The instance of <code>AbsoluteTime</code> object which
072 * will have its time changed. If null, then nothing happens.
073 */
074 public abstract void getTime(AbsoluteTime time);
075
076 /** Set the resolution of <code>this</code>. For some hardware clocks
077 * setting resolution impossible and if called on those nothing happens.
078 *
079 * @param resolutino The new resolution of <code>this</code>.
080 */
081 public abstract void setResolution(RelativeTime resolution);
082 }