Top Description Fields Constructors Methods
stormpot

public final Class Timeout

extends Object
Class Inheritance
Imports
java.time.Duration, java.util.Objects, java.util.concurrent.TimeUnit
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

Field Summary

Modifier and TypeField and Description
private final long
timeout

private final long
timeoutBase

private final TimeUnit
unit

Constructor Summary

AccessConstructor and Description
public
Timeout(long
A numerical value for the timeout. Can be zero or negative, though the meaning is implementation specific.
timeout, TimeUnit
The unit of the timeout value. Never `null`.
unit)

Construct a new timeout with the given value and unit.

public
Timeout(Duration
A duration to use for the timeout.
duration)

Construct a new timeout with the given duration.

Method Summary

Modifier and TypeMethod and Description
public boolean

Returns:

`true` if this Timeout value is equal to the given Timeout value, `false` otherwise.
equals(Object
the reference object with which to compare.
obj)

Overrides java.lang.Object.equals.

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

Returns:

TimeUnit The unit of precision used by the clock in this Timeout.
getBaseUnit()

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

public long

Returns:

A numerical value that represents the deadline from "now" until this timeout has passed.
getDeadline()

Deprecated for removal. 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.
public long

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.
getTimeLeft(long
The reference deadline from getDeadline().
deadline)

Deprecated for removal. 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.
public long

Returns:

A numerical value of the timeout. Possibly zero or negative.
getTimeout()

Get the timeout value in terms of the unit.

public long

Returns:

A numerical value of the timeout. Possibly zero or negative.
getTimeoutInBaseUnit()

Get the timeout value in terms of the base unit.

public TimeUnit

Returns:

The TimeUnit of the timeout value. Never `null`.
getUnit()

Get the unit for the timeout value.

public int
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for this object.
Inherited from java.lang.Object:
clonefinalizegetClassnotifynotifyAlltoStringwaitwaitwait

Field Detail

timeoutback to summary
private final long timeout
timeoutBaseback to summary
private final long timeoutBase
unitback to summary
private final TimeUnit unit

Constructor Detail

Timeoutback to summary
public Timeout(long timeout, 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:long

A numerical value for the timeout. Can be zero or negative, though the meaning is implementation specific.

unit:TimeUnit

The unit of the timeout value. Never `null`.

Timeoutback to summary
public Timeout(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:Duration

A duration to use for the timeout.

Method Detail

equalsback to summary
public boolean equals(Object obj)

Overrides java.lang.Object.equals.

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

Parameters
obj:Object

Doc from java.lang.Object.equals.

the reference object with which to compare.

Returns:boolean

`true` if this Timeout value is equal to the given Timeout value, `false` otherwise.

Annotations
@Override
getBaseUnitback to summary
public TimeUnit getBaseUnit()

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

Returns:TimeUnit

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

getDeadlineback to summary
public long getDeadline()

Deprecated

for removal.

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:long

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

Annotations
@SuppressWarnings:WeakerAccess
@Deprecated
forRemoval:true
getTimeLeftback to summary
public long getTimeLeft(long deadline)

Deprecated

for removal.

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:long

The reference deadline from getDeadline().

Returns:long

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.

Annotations
@SuppressWarnings:WeakerAccess
@Deprecated
forRemoval:true
getTimeoutback to summary
public long getTimeout()

Get the timeout value in terms of the unit.

Returns:long

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

getTimeoutInBaseUnitback to summary
public long getTimeoutInBaseUnit()

Get the timeout value in terms of the base unit.

Returns:long

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

getUnitback to summary
public TimeUnit getUnit()

Get the unit for the timeout value.

Returns:TimeUnit

The TimeUnit of the timeout value. Never `null`.

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Doc from java.lang.Object.hashCode.

Returns a hash code value for this object. This method is supported for the benefit of hash tables such as those provided by java.util.HashMap.

The general contract of hashCode is:

  • Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
  • If two objects are equal according to the equals method, then calling the hashCode method on each of the two objects must produce the same integer result.
  • It is not required that if two objects are unequal according to the equals method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
Returns:int

a hash code value for this object

Annotations
@Override