--- old/src/java.base/share/classes/java/lang/Thread.java 2016-03-10 10:50:27.000000000 -0800 +++ new/src/java.base/share/classes/java/lang/Thread.java 2016-03-10 10:50:27.000000000 -0800 @@ -340,6 +340,44 @@ sleep(millis); } + /** + * 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. + *
+ * 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. + *
{@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 + * . . . + * } + * } + * }+ *
+ * The code above would remain being 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. + *
+ * @since 9 + */ + @HotSpotIntrinsicCandidate + public static void onSpinWait() {} + /** * Initializes a Thread with the current AccessControlContext. * @see #init(ThreadGroup,Runnable,String,long,AccessControlContext,boolean)