Module stormpot
Package stormpot

Class Timeout

  • public final class Timeout
extends java.lang.Object

    A Timeout represents the maximum amount of time a caller is willing to wait for a blocking operation to complete.

    Timeouts are independent of their units, so two timeouts of equivalent duration but constructed in different units, will be equal to each other and work exactly the same.

    Timeouts are also independent of "calendar time" in the sense that they represent and work as a duration of absolute time. In other words, timeouts do not grow or shrink with passing leap seconds or daylight savings time adjustments.

    Author:
    Chris Vest <mr.chrisvest@gmail.com>

    • Constructor Summary

      Constructors 
      Constructor Description
      Timeout​(long timeout, java.util.concurrent.TimeUnit unit)
      Construct a new timeout with the given value and unit.
      Timeout​(java.time.Duration duration)
      Construct a new timeout with the given duration.

    • Method Summary

      All Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean equals​(java.lang.Object obj)
      Timeouts of equivalent duration are equal, even if they were constructed with different units.
      java.util.concurrent.TimeUnit getBaseUnit()
      Get the unit of precision for the underlying clock, that is used by getDeadline() and getTimeLeft(long).
      long getDeadline()
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method is deprecated because it encourages code that is susceptible to overflow bugs.
      long getTimeLeft​(long deadline)
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method is deprecated because it encourages code that is susceptible to overflow bugs.
      long getTimeout()
      Get the timeout value in terms of the unit.
      long getTimeoutInBaseUnit()
      Get the timeout value in terms of the base unit.
      java.util.concurrent.TimeUnit getUnit()
      Get the unit for the timeout value.
      int hashCode()  

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Timeout

        public Timeout​(long timeout,
               java.util.concurrent.TimeUnit unit)

        Construct a new timeout with the given value and unit. The unit cannot be null, but the timeout value is unrestricted. The meaning of a negative timeout value is specific to the implementation of the use site, but typically means that no amount of blocking or waiting is tolerated.

        Parameters:
        timeout - A numerical value for the timeout. Can be zero or negative, though the meaning is implementation specific.
        unit - The unit of the timeout value. Never null.

      • Timeout

        public Timeout​(java.time.Duration duration)

        Construct a new timeout with the given duration. An exception will be thrown if the duration cannot be converted to a nanosecond quantity. The duration also cannot be null. Apart from these two, there are no restrictions on the duration.

        Parameters:
        duration - A duration to use for the timeout.

    • Method Detail

      • getTimeout

        public long getTimeout()

        Get the timeout value in terms of the unit.

        Returns:
        A numerical value of the timeout. Possibly zero or negative.

      • getUnit

        public java.util.concurrent.TimeUnit getUnit()

        Get the unit for the timeout value.

        Returns:
        The TimeUnit of the timeout value. Never null.

      • getDeadline

        @Deprecated(forRemoval=true)
public long getDeadline()
        Deprecated, for removal: This API element is subject to removal in a future version.
        This method is deprecated because it encourages code that is susceptible to overflow bugs.

        Calculate a deadline, as an instant in the future, in terms of the base unit. Once you have a deadline, you can ask how much time is left until it transpires, with the getTimeLeft(long) method, giving the deadline as an argument.

        If the timeout value is really small, zero or negative, then the deadline might be an instant in the past.

        Returns:
        A numerical value that represents the deadline from "now" until this timeout has passed.

      • getTimeoutInBaseUnit

        public long getTimeoutInBaseUnit()

        Get the timeout value in terms of the base unit.

        Returns:
        A numerical value of the timeout. Possibly zero or negative.

      • getTimeLeft

        @Deprecated(forRemoval=true)
public long getTimeLeft​(long deadline)
        Deprecated, for removal: This API element is subject to removal in a future version.
        This method is deprecated because it encourages code that is susceptible to overflow bugs.

        Calculate the amount of time that is left until the deadline, in terms of the base unit. The argument is a deadline value that has been calculated with the getDeadline() method.

        Parameters:
        deadline - The reference deadline from getDeadline().
        Returns:
        The amount of time, in terms of the base unit, that is left until the deadline. If this value is negative, then the deadline has transpired.

      • getBaseUnit

        public java.util.concurrent.TimeUnit getBaseUnit()

        Get the unit of precision for the underlying clock, that is used by getDeadline() and getTimeLeft(long).

        Returns:
        TimeUnit The unit of precision used by the clock in this Timeout.

      • hashCode

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

      • equals

        public boolean equals​(java.lang.Object obj)

        Timeouts of equivalent duration are equal, even if they were constructed with different units.

        Overrides:
        equals in class java.lang.Object
        Returns:
        true if this Timeout value is equal to the given Timeout value, false otherwise.