Change:
use hint::spin_loop; <del> /// Save power or switch hyperthreads in a busy-wait spin-loop. </del> <ins> /// Signals the processor that it is entering a busy-wait spin-loop. </ins> /// <del> /// This function is deliberately more primitive than /// [`std::thread::yield_now`](../../../std/thread/fn.yield_now.html) and /// does not directly yield to the system's scheduler. /// In some cases it might be useful to use a combination of both functions. /// Careful benchmarking is advised. </del> <ins> /// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving /// power or switching hyper-threads. </ins> /// <del> /// On some platforms this function may not do anything at all. </del> <ins> /// This function is different than [`std::thread::yield_now`] which directly yields to the /// system's scheduler, whereas `spin_loop_hint` only signals the processor that it is entering a /// busy-wait spin-loop without yielding control to the system's scheduler. /// /// Using a busy-wait spin-loop with `spin_loop_hint` is ideally used in situations where a /// contended lock is held by another thread executed on a different CPU and where the waiting /// times are relatively small. Because entering busy-wait spin-loop does not trigger the system's /// scheduler, no overhead for switching threads occurs. However, if the thread holding the /// contended lock is running on the same CPU, the spin-loop is likely to occupy an entire CPU slice /// before switching to the thread that holds the lock. If the contending lock is held by a thread /// on the same CPU or if the waiting times for acquiring the lock are longer, it is often better to /// use [`std::thread::yield_now`]. /// /// **Note**: On platforms that do not support receiving spin-loop hints this function does not /// do anything at all. /// /// [`std::thread::yield_now`]: ../../../std/thread/fn.yield_now.html </ins> #[inline] #[stable(feature = "spin_loop_hint", since = "1.24.0")] pub fn spin_loop_hint() {

Discussion:
On the surface, these functions seem very similar. When is it appropriate to use one vs. the other?
Anyone able to describe the differences and use-cases for these functions? I'd be willing to add docs for this, I just don't know when to use either
My understanding for these two functions is: Both are probably not needed in general. While can be a debugging utility in some situations they're largely only needed when writing some form of a spin loop. The function is for very tight spin loops. It is ideally used in situations where you know that a contended lock is held by another thread and you're sure the other thread is running on a different CPU. If the other thread holding a lock (or whatever condition is being waited on in a spin loop) isn't actually running then spinning with this function will eat the entire time slice allocated for the OS until that thread starts running again. This is a CPU instruction on some platforms, and a noop on other platforms. The function invokes the OS scheduler, asking the current thread to basically be put into the back of the run queue. This is best for spin loops where you're pretty certain the lock/condition will become available soon, but you're not sure if the thread holding the lock is running or not. I believe the general wisdom is that on lock contention you for a bit, then a little bit, and finally sleep for real. All of these are pretty advanced functions, though, and the documentation should be very clear that these are largely just current-practice-guidelines and benchmarking and further understanding is highly encouraged
One use case for is a bunch of threads blocked on . potentially needs a large number of cycles to execute but it is also executed in performance-sensitive code (graphics, crypto, etc.) where a full or would not be wanted.
Are you still interested in writing docs for this?
I still don't feel confident to write them given my current level of understanding with these APIs. But if you want to try, go for it!
I will give it a try! I am sure others will correct me if I write some things that are wrong :) I hope I'll be able to deliver a PR somewhere this week.

It seems like you always pop up on my screen when people are talking about technical details so I thought you might be the right man for this question :) When diving into the details of I found this: So basically does a call to which is defined like this: Question: What is the difference in semantics between and ? Or to ask it differently, why should we not deprecate and only use ? The documentation of both functions is exactly the same as well. (Aside being experimental). Or we could maybe re-export as in ?
I did an attempt! I hope it clarifies some things. I didn't edit the documentation to not bloat the documentation there too much. But if that is desired as well, please let me know. The pull is here: