Class Timeout
- Direct Known Subclasses:
AsyncTimeout
,ForwardingTimeout
Timeouts and Deadlines
This class offers two complementary controls to define a timeout policy.Timeouts specify the maximum time to wait for a single operation to complete. Timeouts are typically used to detect problems like network partitions. For example, if a remote peer doesn't return any data for ten seconds, we may assume that the peer is unavailable.
Deadlines specify the maximum time to spend on a job, composed of one or more operations. Use deadlines to set an upper bound on the time invested on a job. For example, a battery-conscious app may limit how much time it spends pre-loading content.
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionClears the deadline.Clears the timeout.final Timeout
Set a deadline of now plusduration
time.long
Returns the nano time when the deadline will be reached.deadlineNanoTime
(long deadlineNanoTime) Sets the nano time when the deadline will be reached.boolean
Returns true if a deadline is enabled.void
Throws anInterruptedIOException
if the deadline has been reached or if the current thread has been interrupted.Wait at mosttimeout
time before aborting an operation.long
Returns the timeout in nanoseconds, or0
for no timeout.final void
waitUntilNotified
(Object monitor) Waits onmonitor
until it is notified.
-
Field Details
-
NONE
An empty timeout that neither tracks nor detects timeouts. Use this when timeouts aren't necessary, such as in implementations whose operations do not block.
-
-
Constructor Details
-
Timeout
public Timeout()
-
-
Method Details
-
timeout
Wait at mosttimeout
time before aborting an operation. Using a per-operation timeout means that as long as forward progress is being made, no sequence of operations will fail.If
timeout == 0
, operations will run indefinitely. (Operating system timeouts may still apply.) -
timeoutNanos
public long timeoutNanos()Returns the timeout in nanoseconds, or0
for no timeout. -
hasDeadline
public boolean hasDeadline()Returns true if a deadline is enabled. -
deadlineNanoTime
public long deadlineNanoTime()Returns the nano time when the deadline will be reached.- Throws:
IllegalStateException
- if no deadline is set.
-
deadlineNanoTime
Sets the nano time when the deadline will be reached. All operations must complete before this time. Use a deadline to set a maximum bound on the time spent on a sequence of operations. -
deadline
Set a deadline of now plusduration
time. -
clearTimeout
Clears the timeout. Operating system timeouts may still apply. -
clearDeadline
Clears the deadline. -
throwIfReached
Throws anInterruptedIOException
if the deadline has been reached or if the current thread has been interrupted. This method doesn't detect timeouts; that should be implemented to asynchronously abort an in-progress operation.- Throws:
IOException
-
waitUntilNotified
Waits onmonitor
until it is notified. ThrowsInterruptedIOException
if either the thread is interrupted or if this timeout elapses beforemonitor
is notified. The caller must be synchronized onmonitor
.Here's a sample class that uses
waitUntilNotified()
to await a specific state. Note that the call is made within a loop to avoid unnecessary waiting and to mitigate spurious notifications.class Dice { Random random = new Random(); int latestTotal; public synchronized void roll() { latestTotal = 2 + random.nextInt(6) + random.nextInt(6); System.out.println("Rolled " + latestTotal); notifyAll(); } public void rollAtFixedRate(int period, TimeUnit timeUnit) { Executors.newScheduledThreadPool(0).scheduleAtFixedRate(new Runnable() { public void run() { roll(); } }, 0, period, timeUnit); } public synchronized void awaitTotal(Timeout timeout, int total) throws InterruptedIOException { while (latestTotal != total) { timeout.waitUntilNotified(this); } } }
- Throws:
InterruptedIOException
-