Package org.threadly.util

Class 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

    • 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)