RFR(XS): 8147844: new method j.l.Thread.onSpinWait() (was j.l.Runtime)

[Hans Boehm]

I would be explicit that this is intended for low-latency spin-waits, and
does not include any intentional delay, wait, or back-off.  It only
notifies the hardware and compiler of programmer intent.

Back-offs can be useful.  I think the intent here is to leave those as the
programmer's responsibility.  It would be nice to be clear about that.


On Wed, Mar 9, 2016 at 8:17 PM, David Holmes <david.holmes at oracle.com>
wrote:

> On 10/03/2016 12:42 PM, Ivan Krylov wrote:
>
>> Hi David,
>>
>> I looked around for more examples and adopted both of your suggestions.
>>
>> New javadoc (should look like the one before except for the horizontal
>> line)
>>
>> http://cr.openjdk.java.net/~ikrylov/8147844.doc.01/java/lang/Thread.html#onSpinWait--
>>
>>
>> I replaced the webrev in place again:
>> http://cr.openjdk.java.net/~ikrylov/8147844.jdk.03
>>
>
> There was nothing wrong, AFAICS, with using the hr or the blockquote - see
> this earlier in Thread:
>
> 79  * <hr><blockquote><pre>
> 80  *     class PrimeThread extends Thread {
>
> Though perhaps a difference between class-level doc and method-level? As
> there seems to be no guidance on this I'm not going to push either way.
>
>
> Thanks,
> David
>
> Thanks,
>>
>> Ivan
>>
>>
>> On 09/03/2016 17:36, David Holmes wrote:
>>
>>> Hi Ivan,
>>>
>>> On 10/03/2016 8:26 AM, Ivan Krylov wrote:
>>>
>>>> I have added a little example that hopefully explains what the new
>>>> method
>>>> is for
>>>>
>>>> JavaDoc:
>>>>
>>>> http://cr.openjdk.java.net/~ikrylov/8147844.doc.00/java/lang/Thread.html#onSpinWait--
>>>>
>>>>
>>>> I replaced the webrev in place:
>>>> http://cr.openjdk.java.net/~ikrylov/8147844.jdk.03
>>>>
>>>
>>> That seems fine to me textually. Thanks for adding the usage example.
>>>
>>> In terms of the HTML I think <code>onSpinWait</code> should be
>>> replaced by {@code onSpinWait}. Also the whole chunk of code in the
>>> <pre> section should(?) also be in a {@code ie:
>>>
>>>       * <hr><blockquote><pre>{@code
>>>       *     class EventHandler {
>>>       ...
>>>       *     }
>>>       * }</pre></blockquote><hr>
>>>
>>> I note that the Thread javadoc doesn't currently utilize {@code }, but
>>> I don't think it should fall to this change to rectify that.
>>>
>>> Thanks,
>>> David
>>>
>>> Thanks,
>>>>
>>>> Ivan
>>>>
>>>>
>>>> On 07/03/2016 17:40, David Holmes wrote:
>>>>
>>>>> Hi Ivan,
>>>>>
>>>>> On 8/03/2016 11:04 AM, Ivan Krylov wrote:
>>>>>
>>>>>> The current wording of what is being called now JEP-285 [1] has placed
>>>>>> onSpinWait() method into j.l.Thread.
>>>>>> Hence, a new revision of the webrev. Everything is the same, except
>>>>>> now
>>>>>> it is the Thread class.
>>>>>>
>>>>>> http://cr.openjdk.java.net/~ikrylov/8147844.jdk.03/
>>>>>>
>>>>>
>>>>> Make sure the commit comment reflects the new synopsis :)
>>>>>
>>>>> I thought at some point there was discussion of giving a usage example
>>>>> in the javadoc? I think most people would be quite puzzled after
>>>>> reading the technical spec alone.
>>>>>
>>>>> Thanks,
>>>>> David
>>>>>
>>>>> Please, approve.
>>>>>>
>>>>>> Thanks,
>>>>>>
>>>>>> Ivan
>>>>>>
>>>>>> [1] - openjdk.java.net/jeps/285
>>>>>>
>>>>>> On 27/01/2016 09:53, Ivan Krylov wrote:
>>>>>>
>>>>>>> Updated to http://cr.openjdk.java.net/~ikrylov/8147844.jdk.02/
>>>>>>> The sample JavaDoc has been updated too:
>>>>>>>
>>>>>>> http://ivankrylov.github.io/onspinwait/api/java/lang/Runtime.html#onSpinWait--
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> Alan, Thank you.
>>>>>>>
>>>>>>> On 27/01/2016 18:20, Alan Bateman wrote:
>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> On 27/01/2016 14:10, Ivan Krylov wrote:
>>>>>>>>
>>>>>>>>> Indeed, thanks!
>>>>>>>>> New webrev http://cr.openjdk.java.net/~ikrylov/8147844.jdk.01/
>>>>>>>>>
>>>>>>>>> Can you add @since 9 too?
>>>>>>>>
>>>>>>>> -Alan.
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>
>>