Package io.grpc

Class Deadline

  • All Implemented Interfaces:
    java.lang.Comparable<Deadline>

    public final class Deadline
    extends java.lang.Object
    implements java.lang.Comparable<Deadline>
    An absolute point in time, generally for tracking when a task should be completed. A deadline is immutable except for the passage of time causing it to expire.

    Many systems use timeouts, which are relative to the start of the operation. However, being relative causes them to be poorly suited for managing higher-level tasks where there are many components and sub-operations that may not know the time of the initial "start of the operation." However, a timeout can be converted to a Deadline at the start of the operation and then passed to the various components unambiguously.

    • Field Detail

      • MAX_OFFSET

        private static final long MAX_OFFSET
      • MIN_OFFSET

        private static final long MIN_OFFSET
      • NANOS_PER_SECOND

        private static final long NANOS_PER_SECOND
      • deadlineNanos

        private final long deadlineNanos
      • expired

        private volatile boolean expired
    • Constructor Detail

      • Deadline

        private Deadline​(Deadline.Ticker ticker,
                         long offset,
                         boolean baseInstantAlreadyExpired)
      • Deadline

        private Deadline​(Deadline.Ticker ticker,
                         long baseInstant,
                         long offset,
                         boolean baseInstantAlreadyExpired)
    • Method Detail

      • getSystemTicker

        public static Deadline.Ticker getSystemTicker()
        Returns the ticker that's based on system clock.

        This is EXPERIMENTAL API and may subject to change. If you'd like it to be stabilized or have any feedback, please let us know.

        Since:
        1.24.0
      • after

        public static Deadline after​(long duration,
                                     java.util.concurrent.TimeUnit units)
        Create a deadline that will expire at the specified offset based on the system ticker.

        If the given offset is extraordinarily long, say 100 years, the actual deadline created might saturate.

        Parameters:
        duration - A non-negative duration.
        units - The time unit for the duration.
        Returns:
        A new deadline.
      • after

        public static Deadline after​(long duration,
                                     java.util.concurrent.TimeUnit units,
                                     Deadline.Ticker ticker)
        Create a deadline that will expire at the specified offset based on the given Deadline.Ticker.

        If the given offset is extraordinarily long, say 100 years, the actual deadline created might saturate.

        CAUTION: Only deadlines created with the same Deadline.Ticker instance can be compared by methods like minimum(io.grpc.Deadline), isBefore(io.grpc.Deadline) and compareTo(io.grpc.Deadline). Custom Tickers should only be used in tests where you fake out the clock. Always use the system ticker in production, or serious errors may occur.

        This is EXPERIMENTAL API and may subject to change. If you'd like it to be stabilized or have any feedback, please let us know.

        Parameters:
        duration - A non-negative duration.
        units - The time unit for the duration.
        ticker - Where this deadline refer the current time
        Returns:
        A new deadline.
        Since:
        1.24.0
      • isExpired

        public boolean isExpired()
        Returns whether this has deadline expired.
        Returns:
        true if it has, otherwise false.
      • isBefore

        public boolean isBefore​(Deadline other)
        Is this deadline before another. Two deadlines must be created using the same Deadline.Ticker.
      • minimum

        public Deadline minimum​(Deadline other)
        Return the minimum deadline of this or an other deadline. They must be created using the same Deadline.Ticker.
        Parameters:
        other - deadline to compare with this.
      • offset

        public Deadline offset​(long offset,
                               java.util.concurrent.TimeUnit units)
        Create a new deadline that is offset from this.

        If the given offset is extraordinarily long, say 100 years, the actual deadline created might saturate.

      • timeRemaining

        public long timeRemaining​(java.util.concurrent.TimeUnit unit)
        How much time is remaining in the specified time unit. Internal units are maintained as nanoseconds and conversions are subject to the constraints documented for TimeUnit.convert(long, java.util.concurrent.TimeUnit). If there is no time remaining, the returned duration is how long ago the deadline expired.
      • runOnExpiration

        public java.util.concurrent.ScheduledFuture<?> runOnExpiration​(java.lang.Runnable task,
                                                                       java.util.concurrent.ScheduledExecutorService scheduler)
        Schedule a task to be run when the deadline expires.

        Note if this deadline was created with a custom Deadline.Ticker, the scheduler's underlying clock should be synchronized with that Ticker. Otherwise the task won't be run at the expected point of time.

        Parameters:
        task - to run on expiration
        scheduler - used to execute the task
        Returns:
        ScheduledFuture which can be used to cancel execution of the task
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • compareTo

        public int compareTo​(Deadline that)

        Both deadlines must be created with the same Deadline.Ticker.

        Specified by:
        compareTo in interface java.lang.Comparable<Deadline>
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object o)
        Overrides:
        equals in class java.lang.Object
      • checkNotNull

        private static <T> T checkNotNull​(T reference,
                                          java.lang.Object errorMessage)
      • checkTicker

        private void checkTicker​(Deadline other)