Class Clock
- java.lang.Object
-
- org.threadly.util.Clock
-
public class Clock extends java.lang.Object
This is a utility class for low-resolution timing which avoids frequentSystem.currentTimeMillis()
calls (which perform poorly because they require system calls).Each call to
lastKnownTimeMillis()
will return the value ofSystem.currentTimeMillis()
as of the last call toaccurateTimeMillis()
. This meanslastKnownTimeMillis()
will only be as accurate as the frequency with whichaccurateTimeMillis()
is called.In order to ensure a minimum level of accuracy, by default a thread is started to call
accurateTimeMillis()
every 100 milliseconds. This can be disabled by callingstopClockUpdateThread()
.- Since:
- 1.0.0
-
-
Field Summary
Fields Modifier and Type Field Description static short
AUTOMATIC_UPDATE_FREQUENCY_IN_MS
This is the frequency at which the thread which regularly updates the clock wakes up and updates the time.static int
NANOS_IN_MILLISECOND
Simple conversion of how many nanoseconds exist within a single millisecond.
-
Constructor Summary
Constructors Constructor Description Clock()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static long
accurateForwardProgressingMillis()
Returns an accurate amount of time in milliseconds since this class has loaded (starting at0
).static long
accurateTimeMillis()
Updates the clock so that future calls tolastKnownTimeMillis()
can benefit, and returns the accurate time in milliseconds.static long
accurateTimeNanos()
This directly returns the result ofSystem.nanoTime()
.static long
forwardProgressingDuration(long forwardMillis)
Finds the duration in milliseconds from the reference time.static long
lastKnownForwardProgressingMillis()
Returns a fuzzy time for how much time in milliseconds since this class has loaded (starting at0
).static long
lastKnownTimeMillis()
Getter for the last known time in milliseconds.static long
lastKnownTimeNanos()
This returns a fuzzy known nano time from invocations to eitheraccurateTimeNanos()
oraccurateForwardProgressingMillis()
.static void
startClockUpdateThread()
Starts a thread to regularly updated the clock automatically.static void
stopClockUpdateThread()
Stops the clock from updating automatically.
-
-
-
Field Detail
-
NANOS_IN_MILLISECOND
public static final int NANOS_IN_MILLISECOND
Simple conversion of how many nanoseconds exist within a single millisecond.- Since:
- 3.1.0
- See Also:
- Constant Field Values
-
AUTOMATIC_UPDATE_FREQUENCY_IN_MS
public static final short AUTOMATIC_UPDATE_FREQUENCY_IN_MS
This is the frequency at which the thread which regularly updates the clock wakes up and updates the time. Invocations toaccurateForwardProgressingMillis()
andaccurateTimeMillis()
both update their respective times, but this will make sure that even if those calls are not made requests tolastKnownForwardProgressingMillis()
andlastKnownTimeMillis()
have at least some level of accuracy.- Since:
- 4.0.0
- See Also:
- Constant Field Values
-
-
Method Detail
-
startClockUpdateThread
public static void startClockUpdateThread()
Starts a thread to regularly updated the clock automatically.
-
stopClockUpdateThread
public static void stopClockUpdateThread()
Stops the clock from updating automatically. This call blocks until the automatic update thread stops, or until this thread is interrupted.
-
accurateTimeNanos
public static long accurateTimeNanos()
This directly returns the result ofSystem.nanoTime()
. Using this as an alternative to invokingSystem.nanoTime()
directly is that it updates the nano time representation, allowing for more accurate time references when callinglastKnownTimeNanos()
andlastKnownForwardProgressingMillis()
.Please read the java documentation about
System.nanoTime()
to understand the nature of this value (it may be positive, negative, overflow, and is completely arbitrary from its start point).- Returns:
- a long which is a constantly forward moving representation of nano seconds
-
lastKnownTimeNanos
public static long lastKnownTimeNanos()
This returns a fuzzy known nano time from invocations to eitheraccurateTimeNanos()
oraccurateForwardProgressingMillis()
. In addition (unless manually stopped viastopClockUpdateThread()
) this time is updated at the frequency ofAUTOMATIC_UPDATE_FREQUENCY_IN_MS
. Thus providing a minimal level of accuracy.Please read the java documentation about
System.nanoTime()
to understand the nature of this value (it may be positive, negative, overflow, and is completely arbitrary from its start point).- Returns:
- a long which is a constantly forward moving representation of nano seconds
-
lastKnownForwardProgressingMillis
public static long lastKnownForwardProgressingMillis()
Returns a fuzzy time for how much time in milliseconds since this class has loaded (starting at0
). IfClock
was loaded at the start of the application, this can provide the amount of time the application has been running.This call is guaranteed to only progress forward, regardless of system clock changes it will move forward at a consistent rate.
By default (unless manually stopped via
stopClockUpdateThread()
) this time is updated automatically at the frequency ofAUTOMATIC_UPDATE_FREQUENCY_IN_MS
. Thus allowing a guarantee of minimal accuracy within the set milliseconds.- Returns:
- Amount of time in milliseconds since Clock class was loaded
- Since:
- 3.1.0
-
accurateForwardProgressingMillis
public static long accurateForwardProgressingMillis()
Returns an accurate amount of time in milliseconds since this class has loaded (starting at0
). IfClock
was loaded at the start of the application, this can provide the amount of time the application has been running. Calls to this will NOT update the time inaccurateTimeMillis()
.This call is guaranteed to only progress forward, regardless of system clock changes it will move forward at a consistent rate.
- Returns:
- Amount of time in milliseconds since Clock class was loaded
- Since:
- 3.1.0
-
forwardProgressingDuration
public static long forwardProgressingDuration(long forwardMillis)
Finds the duration in milliseconds from the reference time. Effectively this is the same as subtracting the result fromlastKnownForwardProgressingMillis()
from the parameter provided. The parameter provided should have been a result fromlastKnownForwardProgressingMillis()
oraccurateForwardProgressingMillis()
. Manipulating that time before calling this is not supported (negative results will not be provided). This is simply a helper function for this very common operation.- Parameters:
forwardMillis
- The reference time- Returns:
- The milliseconds from the provided reference time
-
lastKnownTimeMillis
public static long lastKnownTimeMillis()
Getter for the last known time in milliseconds. This time is considered semi-accurate, based off the last time accurate time has been requested, or this class has automatically updated the time (unless requested to stop automatically updating).If the system clock goes backwards this too can go backwards. If that is not desirable consider using
lastKnownForwardProgressingMillis()
.By default (unless manually stopped via
stopClockUpdateThread()
) this time is updated automatically at the frequency ofAUTOMATIC_UPDATE_FREQUENCY_IN_MS
. Thus allowing a guarantee of minimal accuracy within the set milliseconds.- Returns:
- last known time in milliseconds
-
accurateTimeMillis
public static long accurateTimeMillis()
Updates the clock so that future calls tolastKnownTimeMillis()
can benefit, and returns the accurate time in milliseconds. This will NOT update the time for calls tolastKnownForwardProgressingMillis()
.If the system clock goes backwards this too can go backwards. If that is not desirable consider using
accurateForwardProgressingMillis()
.- Returns:
- accurate time in milliseconds
- Since:
- 2.0.0 (since 1.0.0 as accurateTime)
-
-