org.threadly.util

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 frequent System.currentTimeMillis() calls (which perform poorly because they require system calls).

Each call to lastKnownTimeMillis() will return the value of System.currentTimeMillis() as of the last call to accurateTimeMillis(). This means lastKnownTimeMillis() will only be as accurate as the frequency with which accurateTimeMillis() 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 calling stopClockUpdateThread().

Since:

1.0.0

Field Summary

Fields

Modifier and Type	Field and 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 and Description
Clock()

Method Summary

Modifier and Type	Method and Description
static long	accurateForwardProgressingMillis() Returns an accurate amount of time in milliseconds since this class has loaded (starting at 0).
static long	accurateTimeMillis() Updates the clock so that future calls to lastKnownTimeMillis() can benefit, and returns the accurate time in milliseconds.
static long	accurateTimeNanos() This directly returns the result of System.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 at 0).
static long	lastKnownTimeMillis() Getter for the last known time in milliseconds.
static long	lastKnownTimeNanos() This returns a fuzzy known nano time from invocations to either accurateTimeNanos() or accurateForwardProgressingMillis().
static void	startClockUpdateThread() Starts a thread to regularly updated the clock automatically.
static void	stopClockUpdateThread() Stops the clock from updating automatically.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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 to accurateForwardProgressingMillis() and accurateTimeMillis() both update their respective times, but this will make sure that even if those calls are not made requests to lastKnownForwardProgressingMillis() and lastKnownTimeMillis() have at least some level of accuracy.

Since:

4.0.0

See Also:

Constant Field Values

Constructor Detail

Clock

public Clock()

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 of System.nanoTime(). Using this as an alternative to invoking System.nanoTime() directly is that it updates the nano time representation, allowing for more accurate time references when calling lastKnownTimeNanos() and lastKnownForwardProgressingMillis().

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 either accurateTimeNanos() or accurateForwardProgressingMillis(). In addition (unless manually stopped via stopClockUpdateThread()) this time is updated at the frequency of AUTOMATIC_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 at 0). If Clock 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 of AUTOMATIC_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 at 0). If Clock 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 in accurateTimeMillis().

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 from lastKnownForwardProgressingMillis() from the parameter provided. The parameter provided should have been a result from lastKnownForwardProgressingMillis() or accurateForwardProgressingMillis(). 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 of AUTOMATIC_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 to lastKnownTimeMillis() can benefit, and returns the accurate time in milliseconds. This will NOT update the time for calls to lastKnownForwardProgressingMillis().

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)