51 * how a given timing parameter should be interpreted. For example, |
51 * how a given timing parameter should be interpreted. For example, |
52 * the following code will timeout in 50 milliseconds if the {@link |
52 * the following code will timeout in 50 milliseconds if the {@link |
53 * java.util.concurrent.locks.Lock lock} is not available: |
53 * java.util.concurrent.locks.Lock lock} is not available: |
54 * |
54 * |
55 * <pre> Lock lock = ...; |
55 * <pre> Lock lock = ...; |
56 * if ( lock.tryLock(50L, TimeUnit.MILLISECONDS) ) ... |
56 * if (lock.tryLock(50L, TimeUnit.MILLISECONDS)) ... |
57 * </pre> |
57 * </pre> |
58 * while this code will timeout in 50 seconds: |
58 * while this code will timeout in 50 seconds: |
59 * <pre> |
59 * <pre> |
60 * Lock lock = ...; |
60 * Lock lock = ...; |
61 * if ( lock.tryLock(50L, TimeUnit.SECONDS) ) ... |
61 * if (lock.tryLock(50L, TimeUnit.SECONDS)) ... |
62 * </pre> |
62 * </pre> |
63 * |
63 * |
64 * Note however, that there is no guarantee that a particular timeout |
64 * Note however, that there is no guarantee that a particular timeout |
65 * implementation will be able to notice the passage of time at the |
65 * implementation will be able to notice the passage of time at the |
66 * same granularity as the given <tt>TimeUnit</tt>. |
66 * same granularity as the given <tt>TimeUnit</tt>. |
289 * @return the number of nanoseconds |
289 * @return the number of nanoseconds |
290 */ |
290 */ |
291 abstract int excessNanos(long d, long m); |
291 abstract int excessNanos(long d, long m); |
292 |
292 |
293 /** |
293 /** |
294 * Performs a timed <tt>Object.wait</tt> using this time unit. |
294 * Performs a timed {@link Object#wait(long, int) Object.wait} |
|
295 * using this time unit. |
295 * This is a convenience method that converts timeout arguments |
296 * This is a convenience method that converts timeout arguments |
296 * into the form required by the <tt>Object.wait</tt> method. |
297 * into the form required by the <tt>Object.wait</tt> method. |
297 * |
298 * |
298 * <p>For example, you could implement a blocking <tt>poll</tt> |
299 * <p>For example, you could implement a blocking <tt>poll</tt> |
299 * method (see {@link BlockingQueue#poll BlockingQueue.poll}) |
300 * method (see {@link BlockingQueue#poll BlockingQueue.poll}) |
300 * using: |
301 * using: |
301 * |
302 * |
302 * <pre> public synchronized Object poll(long timeout, TimeUnit unit) throws InterruptedException { |
303 * <pre> {@code |
303 * while (empty) { |
304 * public synchronized Object poll(long timeout, TimeUnit unit) |
304 * unit.timedWait(this, timeout); |
305 * throws InterruptedException { |
305 * ... |
306 * while (empty) { |
306 * } |
307 * unit.timedWait(this, timeout); |
307 * }</pre> |
308 * ... |
|
309 * } |
|
310 * }}</pre> |
308 * |
311 * |
309 * @param obj the object to wait on |
312 * @param obj the object to wait on |
310 * @param timeout the maximum time to wait. If less than |
313 * @param timeout the maximum time to wait. If less than |
311 * or equal to zero, do not wait at all. |
314 * or equal to zero, do not wait at all. |
312 * @throws InterruptedException if interrupted while waiting. |
315 * @throws InterruptedException if interrupted while waiting |
313 * @see Object#wait(long, int) |
|
314 */ |
316 */ |
315 public void timedWait(Object obj, long timeout) |
317 public void timedWait(Object obj, long timeout) |
316 throws InterruptedException { |
318 throws InterruptedException { |
317 if (timeout > 0) { |
319 if (timeout > 0) { |
318 long ms = toMillis(timeout); |
320 long ms = toMillis(timeout); |
319 int ns = excessNanos(timeout, ms); |
321 int ns = excessNanos(timeout, ms); |
320 obj.wait(ms, ns); |
322 obj.wait(ms, ns); |
321 } |
323 } |
322 } |
324 } |
323 |
325 |
324 /** |
326 /** |
325 * Performs a timed <tt>Thread.join</tt> using this time unit. |
327 * Performs a timed {@link Thread#join(long, int) Thread.join} |
|
328 * using this time unit. |
326 * This is a convenience method that converts time arguments into the |
329 * This is a convenience method that converts time arguments into the |
327 * form required by the <tt>Thread.join</tt> method. |
330 * form required by the <tt>Thread.join</tt> method. |
|
331 * |
328 * @param thread the thread to wait for |
332 * @param thread the thread to wait for |
329 * @param timeout the maximum time to wait. If less than |
333 * @param timeout the maximum time to wait. If less than |
330 * or equal to zero, do not wait at all. |
334 * or equal to zero, do not wait at all. |
331 * @throws InterruptedException if interrupted while waiting. |
335 * @throws InterruptedException if interrupted while waiting |
332 * @see Thread#join(long, int) |
|
333 */ |
336 */ |
334 public void timedJoin(Thread thread, long timeout) |
337 public void timedJoin(Thread thread, long timeout) |
335 throws InterruptedException { |
338 throws InterruptedException { |
336 if (timeout > 0) { |
339 if (timeout > 0) { |
337 long ms = toMillis(timeout); |
340 long ms = toMillis(timeout); |
338 int ns = excessNanos(timeout, ms); |
341 int ns = excessNanos(timeout, ms); |
339 thread.join(ms, ns); |
342 thread.join(ms, ns); |
340 } |
343 } |
341 } |
344 } |
342 |
345 |
343 /** |
346 /** |
344 * Performs a <tt>Thread.sleep</tt> using this unit. |
347 * Performs a {@link Thread#sleep(long, int) Thread.sleep} using |
|
348 * this time unit. |
345 * This is a convenience method that converts time arguments into the |
349 * This is a convenience method that converts time arguments into the |
346 * form required by the <tt>Thread.sleep</tt> method. |
350 * form required by the <tt>Thread.sleep</tt> method. |
|
351 * |
347 * @param timeout the minimum time to sleep. If less than |
352 * @param timeout the minimum time to sleep. If less than |
348 * or equal to zero, do not sleep at all. |
353 * or equal to zero, do not sleep at all. |
349 * @throws InterruptedException if interrupted while sleeping. |
354 * @throws InterruptedException if interrupted while sleeping |
350 * @see Thread#sleep |
|
351 */ |
355 */ |
352 public void sleep(long timeout) throws InterruptedException { |
356 public void sleep(long timeout) throws InterruptedException { |
353 if (timeout > 0) { |
357 if (timeout > 0) { |
354 long ms = toMillis(timeout); |
358 long ms = toMillis(timeout); |
355 int ns = excessNanos(timeout, ms); |
359 int ns = excessNanos(timeout, ms); |