Remove wrong advice about spin locks from spin_loop_hint docs

[matklad]

Using a pure spin lock for a critical section in a preemptable thread
is always wrong, however short the critical section may be. The thread
might be preempted, which will cause all other threads to hammer
busily at the core for the whole quant. Moreover, if threads have
different priorities, this might lead to a priority inversion problem
and a deadlock. More generally, a spinlock is not more efficient than
a well-written mutex, which typically does several spin iterations at
the start anyway.

The advise about UP vs SMP is also irrelevant in the context of
preemptive threads.

See also accompanying piece: https://matklad.github.io/2020/01/02/spinlocs-considered-harmful.html

And another, independent piece: https://probablydance.com/2019/12/30/measuring-mutexes-spinlocks-and-how-bad-the-linux-scheduler-really-is

EDIT: obligatory disclosure that I am not an expert in these things, and might be terribly wrong :)

[rust-highfive]

r? @KodrAus

(rust_highfive has picked a reviewer for you, use r? to override)

[steveklabnik]

IMHO, this is a @rust-lang/libs decision; the docs formatting looks fine, but it's up to them for the content.

[Amanieu]

I don't think the advice is wrong. However we could put more emphasis on the underlying assumption that the other thread is running on a different CPU: this is not the case if the other thread has been preempted or interrupted while holding the lock.

[matklad]

I don't think the advice is wrong.

I think it depends on the specific reading of the given docs. One reading is

when implementing locks, it is generally faster to spin for a bit, before making a blocking syscall

This is, in my understanding, 100% correct.

The other plausible reading is

If you can use either std::sync::Mutex or a spinlock, and the critical section is short, a pure spin lock will be more efficient than a sleeping mutex.

I strongly feel that this advise is very wrong. I also feel that the original wording likely implies this reading for a user who is not already familiar with the pitfalls of pure spinlocks. To clarify, there are very specific narrow circumstances where this advice is right (for example, pinned thread per CPU situation with realtime priorities), but in other, more common situations the advice is harmful.

I changed the wording to make it unambiguously refer to the first case. I've also removed the bit about busy polling. It is another plausible use-case for spin_loop_hint, but is more esoteric and doesn't fit into the flow with the new wording. Additionally, the advice to use yield_now or sleep also seems suspicious: it looks like if you want to block in a busy-polling loop, you should just make a blocking syscall like poll/read? (for the curious reader: Linus makes a compelling argumnet that using yield should be avoided: if you are going to call into kernel to sleep, you might as well inform the kernel why you are sleeping (FUTEX_WAIT, poll, etc)).

[matklad]

Oh, I think it also makes sense to r? @Amanieu as well :-)

[Amanieu]

I guess there's always more information we can add about spinlock design, but in the end this doc comment isn't the right place for it.

@bors r+

[bors]

📌 Commit b25eeef has been approved by Amanieu