36 package java.util.concurrent; 37 38 /** 39 * A <tt>TimeUnit</tt> represents time durations at a given unit of 40 * granularity and provides utility methods to convert across units, 41 * and to perform timing and delay operations in these units. A 42 * <tt>TimeUnit</tt> does not maintain time information, but only 43 * helps organize and use time representations that may be maintained 44 * separately across various contexts. A nanosecond is defined as one 45 * thousandth of a microsecond, a microsecond as one thousandth of a 46 * millisecond, a millisecond as one thousandth of a second, a minute 47 * as sixty seconds, an hour as sixty minutes, and a day as twenty four 48 * hours. 49 * 50 * <p>A <tt>TimeUnit</tt> is mainly used to inform time-based methods 51 * how a given timing parameter should be interpreted. For example, 52 * the following code will timeout in 50 milliseconds if the {@link 53 * java.util.concurrent.locks.Lock lock} is not available: 54 * 55 * <pre> Lock lock = ...; 56 * if ( lock.tryLock(50L, TimeUnit.MILLISECONDS) ) ... 57 * </pre> 58 * while this code will timeout in 50 seconds: 59 * <pre> 60 * Lock lock = ...; 61 * if ( lock.tryLock(50L, TimeUnit.SECONDS) ) ... 62 * </pre> 63 * 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 66 * same granularity as the given <tt>TimeUnit</tt>. 67 * 68 * @since 1.5 69 * @author Doug Lea 70 */ 71 public enum TimeUnit { 72 NANOSECONDS { 73 public long toNanos(long d) { return d; } 74 public long toMicros(long d) { return d/(C1/C0); } 75 public long toMillis(long d) { return d/(C2/C0); } 76 public long toSeconds(long d) { return d/(C3/C0); } 77 public long toMinutes(long d) { return d/(C4/C0); } 78 public long toHours(long d) { return d/(C5/C0); } 79 public long toDays(long d) { return d/(C6/C0); } 80 public long convert(long d, TimeUnit u) { return u.toNanos(d); } 81 int excessNanos(long d, long m) { return (int)(d - (m*C2)); } 274 * Equivalent to <tt>DAYS.convert(duration, this)</tt>. 275 * @param duration the duration 276 * @return the converted duration 277 * @see #convert 278 * @since 1.6 279 */ 280 public long toDays(long duration) { 281 throw new AbstractMethodError(); 282 } 283 284 /** 285 * Utility to compute the excess-nanosecond argument to wait, 286 * sleep, join. 287 * @param d the duration 288 * @param m the number of milliseconds 289 * @return the number of nanoseconds 290 */ 291 abstract int excessNanos(long d, long m); 292 293 /** 294 * Performs a timed <tt>Object.wait</tt> using this time unit. 295 * This is a convenience method that converts timeout arguments 296 * into the form required by the <tt>Object.wait</tt> method. 297 * 298 * <p>For example, you could implement a blocking <tt>poll</tt> 299 * method (see {@link BlockingQueue#poll BlockingQueue.poll}) 300 * using: 301 * 302 * <pre> public synchronized Object poll(long timeout, TimeUnit unit) throws InterruptedException { 303 * while (empty) { 304 * unit.timedWait(this, timeout); 305 * ... 306 * } 307 * }</pre> 308 * 309 * @param obj the object to wait on 310 * @param timeout the maximum time to wait. If less than 311 * or equal to zero, do not wait at all. 312 * @throws InterruptedException if interrupted while waiting. 313 * @see Object#wait(long, int) 314 */ 315 public void timedWait(Object obj, long timeout) 316 throws InterruptedException { 317 if (timeout > 0) { 318 long ms = toMillis(timeout); 319 int ns = excessNanos(timeout, ms); 320 obj.wait(ms, ns); 321 } 322 } 323 324 /** 325 * Performs a timed <tt>Thread.join</tt> using this time unit. 326 * This is a convenience method that converts time arguments into the 327 * form required by the <tt>Thread.join</tt> method. 328 * @param thread the thread to wait for 329 * @param timeout the maximum time to wait. If less than 330 * or equal to zero, do not wait at all. 331 * @throws InterruptedException if interrupted while waiting. 332 * @see Thread#join(long, int) 333 */ 334 public void timedJoin(Thread thread, long timeout) 335 throws InterruptedException { 336 if (timeout > 0) { 337 long ms = toMillis(timeout); 338 int ns = excessNanos(timeout, ms); 339 thread.join(ms, ns); 340 } 341 } 342 343 /** 344 * Performs a <tt>Thread.sleep</tt> using this unit. 345 * This is a convenience method that converts time arguments into the 346 * form required by the <tt>Thread.sleep</tt> method. 347 * @param timeout the minimum time to sleep. If less than 348 * or equal to zero, do not sleep at all. 349 * @throws InterruptedException if interrupted while sleeping. 350 * @see Thread#sleep 351 */ 352 public void sleep(long timeout) throws InterruptedException { 353 if (timeout > 0) { 354 long ms = toMillis(timeout); 355 int ns = excessNanos(timeout, ms); 356 Thread.sleep(ms, ns); 357 } 358 } 359 360 } | 36 package java.util.concurrent; 37 38 /** 39 * A <tt>TimeUnit</tt> represents time durations at a given unit of 40 * granularity and provides utility methods to convert across units, 41 * and to perform timing and delay operations in these units. A 42 * <tt>TimeUnit</tt> does not maintain time information, but only 43 * helps organize and use time representations that may be maintained 44 * separately across various contexts. A nanosecond is defined as one 45 * thousandth of a microsecond, a microsecond as one thousandth of a 46 * millisecond, a millisecond as one thousandth of a second, a minute 47 * as sixty seconds, an hour as sixty minutes, and a day as twenty four 48 * hours. 49 * 50 * <p>A <tt>TimeUnit</tt> is mainly used to inform time-based methods 51 * how a given timing parameter should be interpreted. For example, 52 * the following code will timeout in 50 milliseconds if the {@link 53 * java.util.concurrent.locks.Lock lock} is not available: 54 * 55 * <pre> Lock lock = ...; 56 * if (lock.tryLock(50L, TimeUnit.MILLISECONDS)) ... 57 * </pre> 58 * while this code will timeout in 50 seconds: 59 * <pre> 60 * Lock lock = ...; 61 * if (lock.tryLock(50L, TimeUnit.SECONDS)) ... 62 * </pre> 63 * 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 66 * same granularity as the given <tt>TimeUnit</tt>. 67 * 68 * @since 1.5 69 * @author Doug Lea 70 */ 71 public enum TimeUnit { 72 NANOSECONDS { 73 public long toNanos(long d) { return d; } 74 public long toMicros(long d) { return d/(C1/C0); } 75 public long toMillis(long d) { return d/(C2/C0); } 76 public long toSeconds(long d) { return d/(C3/C0); } 77 public long toMinutes(long d) { return d/(C4/C0); } 78 public long toHours(long d) { return d/(C5/C0); } 79 public long toDays(long d) { return d/(C6/C0); } 80 public long convert(long d, TimeUnit u) { return u.toNanos(d); } 81 int excessNanos(long d, long m) { return (int)(d - (m*C2)); } 274 * Equivalent to <tt>DAYS.convert(duration, this)</tt>. 275 * @param duration the duration 276 * @return the converted duration 277 * @see #convert 278 * @since 1.6 279 */ 280 public long toDays(long duration) { 281 throw new AbstractMethodError(); 282 } 283 284 /** 285 * Utility to compute the excess-nanosecond argument to wait, 286 * sleep, join. 287 * @param d the duration 288 * @param m the number of milliseconds 289 * @return the number of nanoseconds 290 */ 291 abstract int excessNanos(long d, long m); 292 293 /** 294 * Performs a timed {@link Object#wait(long, int) Object.wait} 295 * using this time unit. 296 * This is a convenience method that converts timeout arguments 297 * into the form required by the <tt>Object.wait</tt> method. 298 * 299 * <p>For example, you could implement a blocking <tt>poll</tt> 300 * method (see {@link BlockingQueue#poll BlockingQueue.poll}) 301 * using: 302 * 303 * <pre> {@code 304 * public synchronized Object poll(long timeout, TimeUnit unit) 305 * throws InterruptedException { 306 * while (empty) { 307 * unit.timedWait(this, timeout); 308 * ... 309 * } 310 * }}</pre> 311 * 312 * @param obj the object to wait on 313 * @param timeout the maximum time to wait. If less than 314 * or equal to zero, do not wait at all. 315 * @throws InterruptedException if interrupted while waiting 316 */ 317 public void timedWait(Object obj, long timeout) 318 throws InterruptedException { 319 if (timeout > 0) { 320 long ms = toMillis(timeout); 321 int ns = excessNanos(timeout, ms); 322 obj.wait(ms, ns); 323 } 324 } 325 326 /** 327 * Performs a timed {@link Thread#join(long, int) Thread.join} 328 * using this time unit. 329 * This is a convenience method that converts time arguments into the 330 * form required by the <tt>Thread.join</tt> method. 331 * 332 * @param thread the thread to wait for 333 * @param timeout the maximum time to wait. If less than 334 * or equal to zero, do not wait at all. 335 * @throws InterruptedException if interrupted while waiting 336 */ 337 public void timedJoin(Thread thread, long timeout) 338 throws InterruptedException { 339 if (timeout > 0) { 340 long ms = toMillis(timeout); 341 int ns = excessNanos(timeout, ms); 342 thread.join(ms, ns); 343 } 344 } 345 346 /** 347 * Performs a {@link Thread#sleep(long, int) Thread.sleep} using 348 * this time unit. 349 * This is a convenience method that converts time arguments into the 350 * form required by the <tt>Thread.sleep</tt> method. 351 * 352 * @param timeout the minimum time to sleep. If less than 353 * or equal to zero, do not sleep at all. 354 * @throws InterruptedException if interrupted while sleeping 355 */ 356 public void sleep(long timeout) throws InterruptedException { 357 if (timeout > 0) { 358 long ms = toMillis(timeout); 359 int ns = excessNanos(timeout, ms); 360 Thread.sleep(ms, ns); 361 } 362 } 363 364 } |