io.grpc

Class Deadline

java.lang.Object

io.grpc.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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Deadline.Ticker Time source representing nanoseconds since fixed but arbitrary point in time.

Method Summary

Modifier and Type	Method and Description
static Deadline	after(long duration, TimeUnit units) Create a deadline that will expire at the specified offset based on the system ticker.
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.
int	compareTo(Deadline that)
boolean	equals(Object o)
static Deadline.Ticker	getSystemTicker() Returns the ticker that's based on system clock.
int	hashCode()
boolean	isBefore(Deadline other) Is this deadline before another.
boolean	isExpired() Has this deadline expired
Deadline	minimum(Deadline other) Return the minimum deadline of this or an other deadline.
Deadline	offset(long offset, TimeUnit units) Create a new deadline that is offset from this.
ScheduledFuture<?>	runOnExpiration(Runnable task, ScheduledExecutorService scheduler) Schedule a task to be run when the deadline expires.
long	timeRemaining(TimeUnit unit) How much time is remaining in the specified time unit.
String	toString()

Methods inherited from class java.lang.Object

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

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

Has this 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

toString

public String toString()

Overrides:

toString in class Object

compareTo

public int compareTo(Deadline that)

Both deadlines must be created with the same Deadline.Ticker.

Specified by:

compareTo in interface Comparable<Deadline>

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object