Package io.grpc

Class Deadline

java.lang.Object
io.grpc.Deadline
All Implemented Interfaces:
Comparable<Deadline>
public final class Deadline extends Object implements 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.

  • Method Details

    • 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, 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, 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, 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(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 ScheduledFuture<?> runOnExpiration(Runnable task, 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 String toString()
      Overrides:
      toString in class Object

    • compareTo

      public int compareTo(Deadline that)

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

      Specified by:
      compareTo in interface Comparable<Deadline>

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object