Re: The code example in onSpinWait() Javadoc

On 11/16/19 4:15 AM, Andrew Haley via Concurrency-interest wrote:
> On 11/15/19 3:55 PM, Roman Leventov wrote:
>> I agree that Javadoc code shouldn't be a tutorial - that is why I also
>> proposed to delete the example completely. But I think the current example
>> is a little bit of anti-tutorial. To cite Josh Bloch - "Example code should
>> be exemplary. If an API is used widely, its examples will be the archetypes
>> for thousands of programs. Any mistakes will come back to haunt you a
>> thousand fold."
> 
> So far all that you have done is assert that there is something wrong
> with the example. I have seen nothing remotely convincing about what
> is wrong with it. The example, as posted, shows exactly how the
> intrinsic should be used in a spin loop.
> 
> Here you say:
> 
>> By "half-baked" I meant specifically that the example could be valid but
>> only under specific conditions, such as core-pinned thread, or backoff
>> timeout event, etc.
> 
> All code is only valid under specific conditions. This specific
> condition is spinning, which should only be done for a short while
> when you know that a lock is only held for a short while. Anybody who
> wants to know the advantages and disadvantages of spinning can go to
> the Wikipedia page https://en.wikipedia.org/wiki/Spinlock.
> 

I agree with all of this. I think the underlying concern is that we
don't include anything discussing the tradeoffs about when to use
spin-loops. Which we don't mainly because it is less straightforward
than in C. Usage may interact with GC, reference handling, and
safepoints: in some contexts "a short while" isn't usually short, but we
don't have a way of portably discussing such issues in javadocs. It's
also one of the reasons we don't include a spinlock utility -- we cannot
easily guess how best to write one that works well across enough usage
contexts. (But we do make it easy to write them via tryLock.)

-Doug

_______________________________________________
Concurrency-interest mailing list
[email protected]
http://cs.oswego.edu/mailman/listinfo/concurrency-interest