# HG changeset patch
# User ikrylov
# Date 1459350249 -7200
# Node ID 80e6a5993e3d56a7e463729dbbbf56970420a224
# Parent  f218fd1bb19efab38fb1b3bca7c630102f964f25
8147844: new method j.l.Thread.onSpinWait() and the corresponding x86 hotspot instrinsic
Summary: see JEP-285 for details
Reviewed-by: psandoz, alanb, dholmes
Contributed-by: Gil Tene <gil@azul.com>, Ivan Krylov <ivan@azul.com>

diff -r f218fd1bb19e -r 80e6a5993e3d jdk/src/java.base/share/classes/java/lang/Thread.java
--- a/jdk/src/java.base/share/classes/java/lang/Thread.java	Tue Apr 05 15:39:38 2016 -0400
+++ b/jdk/src/java.base/share/classes/java/lang/Thread.java	Wed Mar 30 17:04:09 2016 +0200
@@ -341,6 +341,45 @@
     }
 
     /**
+     * Indicates that the caller is momentarily unable to progress, until the
+     * occurrence of one or more actions on the part of other activities. By
+     * invoking this method within each iteration of a spin-wait loop construct,
+     * the calling thread indicates to the runtime that it is busy-waiting.
+     * The runtime may take action to improve the performance of invoking
+     * spin-wait loop constructions.
+     * <p>
+     * @apiNote
+     * As an example consider a method in a class that spins in a loop until
+     * some flag is set outside of that method. A call to the {@code onSpinWait}
+     * method should be placed inside the spin loop.
+     * <pre>{@code
+     *     class EventHandler {
+     *         volatile boolean eventNotificationNotReceived;
+     *         void waitForEventAndHandleIt() {
+     *             while ( eventNotificationNotReceived ) {
+     *                 java.lang.Thread.onSpinWait();
+     *             }
+     *             readAndProcessEvent();
+     *         }
+     *
+     *         void readAndProcessEvent() {
+     *             // Read event from some source and process it
+     *              . . .
+     *         }
+     *     }
+     * }</pre>
+     * <p>
+     * The code above would remain correct even if the {@code onSpinWait}
+     * method was not called at all. However on some architectures the Java
+     * Virtual Machine may issue the processor instructions to address such
+     * code patterns in a more beneficial way.
+     * <p>
+     * @since 9
+     */
+    @HotSpotIntrinsicCandidate
+    public static void onSpinWait() {}
+
+    /**
      * Initializes a Thread with the current AccessControlContext.
      * @see #init(ThreadGroup,Runnable,String,long,AccessControlContext,boolean)
      */