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

Print this page
rev 11263 : 8069269: (spec) Defect in the System.nanoTime spec
Summary: Change description of suggested way to compare two nanoTime values.
Reviewed-by: TBD


 360      * The value returned represents nanoseconds since some fixed but
 361      * arbitrary <i>origin</i> time (perhaps in the future, so values
 362      * may be negative).  The same origin is used by all invocations of
 363      * this method in an instance of a Java virtual machine; other
 364      * virtual machine instances are likely to use a different origin.
 365      *
 366      * <p>This method provides nanosecond precision, but not necessarily
 367      * nanosecond resolution (that is, how frequently the value changes)
 368      * - no guarantees are made except that the resolution is at least as
 369      * good as that of {@link #currentTimeMillis()}.
 370      *
 371      * <p>Differences in successive calls that span greater than
 372      * approximately 292 years (2<sup>63</sup> nanoseconds) will not
 373      * correctly compute elapsed time due to numerical overflow.
 374      *
 375      * <p>The values returned by this method become meaningful only when
 376      * the difference between two such values, obtained within the same
 377      * instance of a Java virtual machine, is computed.
 378      *
 379      * <p> For example, to measure how long some code takes to execute:
 380      *  <pre> {@code
 381      * long startTime = System.nanoTime();
 382      * // ... the code being measured ...
 383      * long estimatedTime = System.nanoTime() - startTime;}</pre>

 384      *
 385      * <p>To compare two nanoTime values
 386      *  <pre> {@code
 387      * long t0 = System.nanoTime();
 388      * ...
 389      * long t1 = System.nanoTime();}</pre>

 390      *
 391      * one should use {@code t1 - t0 < 0}, not {@code t1 < t0},
 392      * because of the possibility of numerical overflow.
 393      *
 394      * @return the current value of the running Java Virtual Machine's
 395      *         high-resolution time source, in nanoseconds
 396      * @since 1.5
 397      */
 398     public static native long nanoTime();
 399 
 400     /**
 401      * Copies an array from the specified source array, beginning at the
 402      * specified position, to the specified position of the destination array.
 403      * A subsequence of array components are copied from the source
 404      * array referenced by <code>src</code> to the destination array
 405      * referenced by <code>dest</code>. The number of components copied is
 406      * equal to the <code>length</code> argument. The components at
 407      * positions <code>srcPos</code> through
 408      * <code>srcPos+length-1</code> in the source array are copied into
 409      * positions <code>destPos</code> through
 410      * <code>destPos+length-1</code>, respectively, of the destination
 411      * array.




 360      * The value returned represents nanoseconds since some fixed but
 361      * arbitrary <i>origin</i> time (perhaps in the future, so values
 362      * may be negative).  The same origin is used by all invocations of
 363      * this method in an instance of a Java virtual machine; other
 364      * virtual machine instances are likely to use a different origin.
 365      *
 366      * <p>This method provides nanosecond precision, but not necessarily
 367      * nanosecond resolution (that is, how frequently the value changes)
 368      * - no guarantees are made except that the resolution is at least as
 369      * good as that of {@link #currentTimeMillis()}.
 370      *
 371      * <p>Differences in successive calls that span greater than
 372      * approximately 292 years (2<sup>63</sup> nanoseconds) will not
 373      * correctly compute elapsed time due to numerical overflow.
 374      *
 375      * <p>The values returned by this method become meaningful only when
 376      * the difference between two such values, obtained within the same
 377      * instance of a Java virtual machine, is computed.
 378      *
 379      * <p> For example, to measure how long some code takes to execute:
 380      * <pre>{@code
 381      * long startTime = System.nanoTime();
 382      * // ... the code being measured ...
 383      * long estimatedTime = System.nanoTime() - startTime;
 384      * }</pre>
 385      *
 386      * <p>To compare two nanoTime values
 387      * <pre>{@code
 388      * long t0 = System.nanoTime();
 389      * ...
 390      * long t1 = System.nanoTime();
 391      * }</pre>
 392      *
 393      * one should use {@code t0 - t1 < 0}, not {@code t0 < t1},
 394      * because of the possibility of numerical overflow.
 395      *
 396      * @return the current value of the running Java Virtual Machine's
 397      *         high-resolution time source, in nanoseconds
 398      * @since 1.5
 399      */
 400     public static native long nanoTime();
 401 
 402     /**
 403      * Copies an array from the specified source array, beginning at the
 404      * specified position, to the specified position of the destination array.
 405      * A subsequence of array components are copied from the source
 406      * array referenced by <code>src</code> to the destination array
 407      * referenced by <code>dest</code>. The number of components copied is
 408      * equal to the <code>length</code> argument. The components at
 409      * positions <code>srcPos</code> through
 410      * <code>srcPos+length-1</code> in the source array are copied into
 411      * positions <code>destPos</code> through
 412      * <code>destPos+length-1</code>, respectively, of the destination
 413      * array.