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.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Deadline.Ticker
      Time source representing nanoseconds since fixed but arbitrary point in time.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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.
      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.
      int compareTo​(Deadline that)
      boolean equals​(java.lang.Object o)  
      static Deadline.Ticker getSystemTicker()
      Returns the ticker that's based on system clock.
      int hashCode()  
      boolean isBefore​(Deadline other)
      Is this deadline before another.
      boolean isExpired()
      Returns whether this has deadline expired.
      Deadline minimum​(Deadline other)
      Return the minimum deadline of this or an other deadline.
      Deadline offset​(long offset, java.util.concurrent.TimeUnit units)
      Create a new deadline that is offset from this.
      java.util.concurrent.ScheduledFuture<?> runOnExpiration​(java.lang.Runnable task, java.util.concurrent.ScheduledExecutorService scheduler)
      Schedule a task to be run when the deadline expires.
      long timeRemaining​(java.util.concurrent.TimeUnit unit)
      How much time is remaining in the specified time unit.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • 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