stormpot

Class Timeout

java.lang.Object

stormpot.Timeout

public class Timeout
extends 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 and Description
Timeout(long timeout, TimeUnit unit) Construct a new timeout with the given value and unit.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object obj) Timeouts of equivalent duration are equal, even if they were constructed with different units.
TimeUnit	getBaseUnit() Get the unit of precision for the underlying clock, that is used by getDeadline() and getTimeLeft(long).
long	getDeadline() Calculate a deadline, as an instant in the future, in terms of the base unit.
long	getTimeLeft(long deadline) Calculate the amount of time that is left until the deadline, in terms of the base unit.
long	getTimeout() Get the timeout value in terms of the unit.
long	getTimeoutInBaseUnit() Get the timeout value in terms of the base unit.
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,
               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.

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 TimeUnit getUnit()

Get the unit for the timeout value.

Returns:

The TimeUnit of the timeout value. Never null.

getDeadline

public long getDeadline()

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

public long getTimeLeft(long deadline)

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 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 Object

equals

public boolean equals(Object obj)

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

Overrides:

equals in class Object

Returns:

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