src/java.base/share/classes/java/lang/System.java

rev 11317 : 8069269: (spec) Defect in the System.nanoTime spec
Summary: Change the description of how to compare two nanoTime values.
Reviewed-by: TBD

*** 374,396 ****
       *
       * <p>The values returned by this method become meaningful only when
       * the difference between two such values, obtained within the same
       * instance of a Java virtual machine, is computed.
       *
!      * <p> For example, to measure how long some code takes to execute:
       *  <pre> {@code
       * long startTime = System.nanoTime();
       * // ... the code being measured ...
!      * long estimatedTime = System.nanoTime() - startTime;}</pre>
       *
!      * <p>To compare two nanoTime values
!      *  <pre> {@code
!      * long t0 = System.nanoTime();
!      * ...
!      * long t1 = System.nanoTime();}</pre>
!      *
!      * one should use {@code t1 - t0 < 0}, not {@code t1 < t0},
       * because of the possibility of numerical overflow.
       *
       * @return the current value of the running Java Virtual Machine's
       *         high-resolution time source, in nanoseconds
       * @since 1.5
--- 374,393 ----
       *
       * <p>The values returned by this method become meaningful only when
       * the difference between two such values, obtained within the same
       * instance of a Java virtual machine, is computed.
       *
!      * <p>For example, to measure how long some code takes to execute:
       * <pre> {@code
       * long startTime = System.nanoTime();
       * // ... the code being measured ...
!      * long elapsedNanos = System.nanoTime() - startTime;}</pre>
       *
!      * <p>To compare elapsed time against a timeout, use <pre> {@code
!      * if (System.nanoTime() - startTime >= timeoutNanos) ...}</pre>
!      * instead of <pre> {@code
!      * if (System.nanoTime() >= startTime + timeoutNanos) ...}</pre>
       * because of the possibility of numerical overflow.
       *
       * @return the current value of the running Java Virtual Machine's
       *         high-resolution time source, in nanoseconds
       * @since 1.5