Package io.grpc

Class 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 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,
                             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

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object