src/share/classes/java/util/concurrent/TimeUnit.java

Print this page




  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 }