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

Print this page
rev 13792 : 8147844: new method j.l.Thread.onSpinWait() and the corresponding x86 hotspot instrinsic
Summary: see JEP-285 for details
Contributed-by: Gil Tene <gil@azul.com>, ikrylov
Reviewed-by: psandoz, alanb, dholmes


 324      */
 325     public static void sleep(long millis, int nanos)
 326     throws InterruptedException {
 327         if (millis < 0) {
 328             throw new IllegalArgumentException("timeout value is negative");
 329         }
 330 
 331         if (nanos < 0 || nanos > 999999) {
 332             throw new IllegalArgumentException(
 333                                 "nanosecond timeout value out of range");
 334         }
 335 
 336         if (nanos >= 500000 || (nanos != 0 && millis == 0)) {
 337             millis++;
 338         }
 339 
 340         sleep(millis);
 341     }
 342 
 343     /**






































 344      * Initializes a Thread with the current AccessControlContext.
 345      * @see #init(ThreadGroup,Runnable,String,long,AccessControlContext,boolean)
 346      */
 347     private void init(ThreadGroup g, Runnable target, String name,
 348                       long stackSize) {
 349         init(g, target, name, stackSize, null, true);
 350     }
 351 
 352     /**
 353      * Initializes a Thread.
 354      *
 355      * @param g the Thread group
 356      * @param target the object whose run() method gets called
 357      * @param name the name of the new Thread
 358      * @param stackSize the desired stack size for the new thread, or
 359      *        zero to indicate that this parameter is to be ignored.
 360      * @param acc the AccessControlContext to inherit, or
 361      *            AccessController.getContext() if null
 362      * @param inheritThreadLocals if {@code true}, inherit initial values for
 363      *            inheritable thread-locals from the constructing thread




 324      */
 325     public static void sleep(long millis, int nanos)
 326     throws InterruptedException {
 327         if (millis < 0) {
 328             throw new IllegalArgumentException("timeout value is negative");
 329         }
 330 
 331         if (nanos < 0 || nanos > 999999) {
 332             throw new IllegalArgumentException(
 333                                 "nanosecond timeout value out of range");
 334         }
 335 
 336         if (nanos >= 500000 || (nanos != 0 && millis == 0)) {
 337             millis++;
 338         }
 339 
 340         sleep(millis);
 341     }
 342 
 343     /** 
 344      * Indicates that the caller is momentarily unable to progress, until the
 345      * occurrence of one or more actions on the part of other activities.  By
 346      * invoking this method within each iteration of a spin-wait loop construct,
 347      * the calling thread indicates to the runtime that it is busy-waiting. The runtime
 348      * may take action to improve the performance of invoking spin-wait loop
 349      * constructions.
 350      * <p>
 351      * As an example consider a method in a class that spins in a loop until 
 352      * some flag is set outside of that method. A call to the {@code onSpinWait} 
 353      * method should be placed inside the spin loop. 
 354      * <pre>{@code
 355      *     class EventHandler {
 356      *         volatile boolean eventNotificationNotReceived;
 357      *         void waitForEventAndHandleIt() {
 358      *             while ( eventNotificationNotReceived ) {
 359      *                 java.lang.Thread.onSpinWait();
 360      *             }
 361      *             readAndProcessEvent();
 362      *         }
 363      *
 364      *         void readAndProcessEvent() {
 365      *             // Read event from some source and process it
 366      *              . . .
 367      *         }
 368      *     }
 369      * }</pre>
 370      * <p>
 371      * The code above would remain being correct even if the {@code onSpinWait} 
 372      * method was not called at all. However on some architectures the Java Virtual 
 373      * Machine may issue the processor instructions to address such code patterns 
 374      * in a more beneficial way.
 375      * <p>
 376      * @since 9
 377      */
 378     @HotSpotIntrinsicCandidate
 379     public static void onSpinWait() {}
 380 
 381     /**
 382      * Initializes a Thread with the current AccessControlContext.
 383      * @see #init(ThreadGroup,Runnable,String,long,AccessControlContext,boolean)
 384      */
 385     private void init(ThreadGroup g, Runnable target, String name,
 386                       long stackSize) {
 387         init(g, target, name, stackSize, null, true);
 388     }
 389 
 390     /**
 391      * Initializes a Thread.
 392      *
 393      * @param g the Thread group
 394      * @param target the object whose run() method gets called
 395      * @param name the name of the new Thread
 396      * @param stackSize the desired stack size for the new thread, or
 397      *        zero to indicate that this parameter is to be ignored.
 398      * @param acc the AccessControlContext to inherit, or
 399      *            AccessController.getContext() if null
 400      * @param inheritThreadLocals if {@code true}, inherit initial values for
 401      *            inheritable thread-locals from the constructing thread