io.atlassian.util.concurrent

Class Timeout

java.lang.Object

io.atlassian.util.concurrent.Timeout

@Immutable
public final class Timeout
extends Object

Automatically calculates elapsed time from when it is created. Useful when successively calling blocking methods and a time since call time needs to be worked out.

Usage:

 Timeout timeout = Timeout.getNanosTimeout(1, TimeUnit.SECONDS);
 String str = futureString.get(timeout.getTime(), timeout.getUnit());
 Integer num = futureInt.get(timeout.getTime(), timeout.getUnit());
 

where if the first call takes quarter of a second, the second call is passed the equivalent of three-quarters of a second.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	Timeout.TimeSupplier Supply time and precision to a Timeout.

Method Summary

Modifier and Type	Method and Description
static Timeout	getMillisTimeout(long time, TimeUnit unit) Get a Timeout that uses millisecond precision.
static Timeout	getNanosTimeout(long time, TimeUnit unit) Get a Timeout that uses nanosecond precision.
long	getTime() Get time remaining
RuntimeTimeoutException	getTimeoutException() Build a new time out exception for this timeout
long	getTimeoutPeriod() The original timeout period expressed in units
TimeUnit	getUnit() Get the precision of this timeout.
boolean	isExpired() Has this timeout expired
void	throwTimeoutException() Always throws a TimeoutException.
static Supplier<Timeout>	timeoutFactory(long time, TimeUnit unit, Timeout.TimeSupplier supplier) Factory for creating timeouts of the specified duration.

Methods inherited from class java.lang.Object

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

Method Detail

getNanosTimeout

public static Timeout getNanosTimeout(long time,
                                      TimeUnit unit)

Get a Timeout that uses nanosecond precision. The accuracy will depend on the accuracy of System.nanoTime().

Parameters:

time - the maximum time to wait for the lock

unit - the time unit of the time argument.

Returns:

timeout with TimeUnit.NANOSECONDS precision.

getMillisTimeout

public static Timeout getMillisTimeout(long time,
                                       TimeUnit unit)

Get a Timeout that uses millisecond precision. The accuracy will depend on the accuracy of System.currentTimeMillis().

Parameters:

time - the maximum time to wait for the lock

unit - the time unit of the time argument.

Returns:

timeout with TimeUnit.MILLISECONDS precision.

timeoutFactory

public static Supplier<Timeout> timeoutFactory(long time,
                                               TimeUnit unit,
                                               Timeout.TimeSupplier supplier)

Factory for creating timeouts of the specified duration. Each Timeout will start when the factory is called.

Generally, use the getMillisTimeout(long, TimeUnit) or getNanosTimeout(long, TimeUnit) factory methods directly. Only use this if a custom Timeout.TimeSupplier is required – for instance for testing, you can use this to mock out the actual passage of time.

Parameters:

time - how long the timeouts should be for

unit - in what units time is expressed in

supplier - the thing that tells the timeout what the current time is.

Returns:

a Supplier.

Since:

2.2

getTime

public long getTime()

Get time remaining

Returns:

a long.

getUnit

public TimeUnit getUnit()

Get the precision of this timeout.

Returns:

a TimeUnit.

isExpired

public boolean isExpired()

Has this timeout expired

Returns:

true if expired

getTimeoutPeriod

public long getTimeoutPeriod()

The original timeout period expressed in units

Returns:

a long.

Since:

2.2

throwTimeoutException

public void throwTimeoutException()
                           throws TimedOutException

Always throws a TimeoutException.

Throws:

TimedOutException - if any.

getTimeoutException

public RuntimeTimeoutException getTimeoutException()

Build a new time out exception for this timeout

Returns:

a RuntimeTimeoutException.