< prev index next >

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

Print this page




  18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  19  *
  20  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  21  * or visit www.oracle.com if you need additional information or have any
  22  * questions.
  23  */
  24 
  25 /*
  26  * This file is available under and governed by the GNU General Public
  27  * License version 2 only, as published by the Free Software Foundation.
  28  * However, the following notice accompanied the original version of this
  29  * file:
  30  *
  31  * Written by Doug Lea with assistance from members of JCP JSR-166
  32  * Expert Group and released to the public domain, as explained at
  33  * http://creativecommons.org/publicdomain/zero/1.0/
  34  */
  35 
  36 package java.util.concurrent;
  37 



  38 /**
  39  * A {@code TimeUnit} 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  * {@code TimeUnit} 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 {@code TimeUnit} 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> {@code
  56  * Lock lock = ...;
  57  * if (lock.tryLock(50L, TimeUnit.MILLISECONDS)) ...}</pre>


 373     }
 374 
 375     /**
 376      * Performs a {@link Thread#sleep(long, int) Thread.sleep} using
 377      * this time unit.
 378      * This is a convenience method that converts time arguments into the
 379      * form required by the {@code Thread.sleep} method.
 380      *
 381      * @param timeout the minimum time to sleep. If less than
 382      * or equal to zero, do not sleep at all.
 383      * @throws InterruptedException if interrupted while sleeping
 384      */
 385     public void sleep(long timeout) throws InterruptedException {
 386         if (timeout > 0) {
 387             long ms = toMillis(timeout);
 388             int ns = excessNanos(timeout, ms);
 389             Thread.sleep(ms, ns);
 390         }
 391     }
 392 




























































 393 }


  18  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  19  *
  20  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  21  * or visit www.oracle.com if you need additional information or have any
  22  * questions.
  23  */
  24 
  25 /*
  26  * This file is available under and governed by the GNU General Public
  27  * License version 2 only, as published by the Free Software Foundation.
  28  * However, the following notice accompanied the original version of this
  29  * file:
  30  *
  31  * Written by Doug Lea with assistance from members of JCP JSR-166
  32  * Expert Group and released to the public domain, as explained at
  33  * http://creativecommons.org/publicdomain/zero/1.0/
  34  */
  35 
  36 package java.util.concurrent;
  37 
  38 import java.time.temporal.ChronoUnit;
  39 import java.util.Objects;
  40 
  41 /**
  42  * A {@code TimeUnit} represents time durations at a given unit of
  43  * granularity and provides utility methods to convert across units,
  44  * and to perform timing and delay operations in these units.  A
  45  * {@code TimeUnit} does not maintain time information, but only
  46  * helps organize and use time representations that may be maintained
  47  * separately across various contexts.  A nanosecond is defined as one
  48  * thousandth of a microsecond, a microsecond as one thousandth of a
  49  * millisecond, a millisecond as one thousandth of a second, a minute
  50  * as sixty seconds, an hour as sixty minutes, and a day as twenty four
  51  * hours.
  52  *
  53  * <p>A {@code TimeUnit} is mainly used to inform time-based methods
  54  * how a given timing parameter should be interpreted. For example,
  55  * the following code will timeout in 50 milliseconds if the {@link
  56  * java.util.concurrent.locks.Lock lock} is not available:
  57  *
  58  * <pre> {@code
  59  * Lock lock = ...;
  60  * if (lock.tryLock(50L, TimeUnit.MILLISECONDS)) ...}</pre>


 376     }
 377 
 378     /**
 379      * Performs a {@link Thread#sleep(long, int) Thread.sleep} using
 380      * this time unit.
 381      * This is a convenience method that converts time arguments into the
 382      * form required by the {@code Thread.sleep} method.
 383      *
 384      * @param timeout the minimum time to sleep. If less than
 385      * or equal to zero, do not sleep at all.
 386      * @throws InterruptedException if interrupted while sleeping
 387      */
 388     public void sleep(long timeout) throws InterruptedException {
 389         if (timeout > 0) {
 390             long ms = toMillis(timeout);
 391             int ns = excessNanos(timeout, ms);
 392             Thread.sleep(ms, ns);
 393         }
 394     }
 395 
 396     /**
 397      * Converts a {@code TimeUnit} to an equivalent {@code ChronoUnit}.
 398      *
 399      * @param  timeUnit the timeUnit to convert, not null
 400      * @return the converted equivalent chronoUnit
 401      * @throws IllegalArgumentException if the unit cannot be converted
 402      * @since 9
 403      */
 404     public static ChronoUnit toChronoUnit(TimeUnit timeUnit) {
 405         Objects.requireNonNull(timeUnit, "timeUnit");
 406         switch (timeUnit) {
 407             case NANOSECONDS:
 408                 return ChronoUnit.NANOS;
 409             case MICROSECONDS:
 410                 return ChronoUnit.MICROS;
 411             case MILLISECONDS:
 412                 return ChronoUnit.MILLIS;
 413             case SECONDS:
 414                 return ChronoUnit.SECONDS;
 415             case MINUTES:
 416                 return ChronoUnit.MINUTES;
 417             case HOURS:
 418                 return ChronoUnit.HOURS;
 419             case DAYS:
 420                 return ChronoUnit.DAYS;
 421             default:
 422                 throw new IllegalArgumentException("Unknown TimeUnit");
 423         }
 424     }
 425 
 426     /**
 427      * Converts a {@code ChronoUnit} to an equivalent {@code TimeUnit}.
 428      *
 429      * @param chronoUnit  the unit to convert, not null
 430      * @return the converted equivalent timeUnit
 431      * @throws IllegalArgumentException if the unit cannot be converted
 432      * @since 9
 433      */
 434     public static TimeUnit of(ChronoUnit chronoUnit) {
 435         Objects.requireNonNull(chronoUnit, "chronoUnit");
 436         switch (chronoUnit) {
 437             case NANOS:
 438                 return TimeUnit.NANOSECONDS;
 439             case MICROS:
 440                 return TimeUnit.MICROSECONDS;
 441             case MILLIS:
 442                 return TimeUnit.MILLISECONDS;
 443             case SECONDS:
 444                 return TimeUnit.SECONDS;
 445             case MINUTES:
 446                 return TimeUnit.MINUTES;
 447             case HOURS:
 448                 return TimeUnit.HOURS;
 449             case DAYS:
 450                 return TimeUnit.DAYS;
 451             default:
 452                 throw new IllegalArgumentException("No TimeUnit equivalent for " + chronoUnit);
 453         }
 454     }
 455 
 456 }
< prev index next >