From ab3b65737380d2c2a15a868452026df49c58131a Mon Sep 17 00:00:00 2001 From: Christian Date: Wed, 3 Apr 2019 10:54:07 +0200 Subject: [PATCH 1/2] Updated the documentation of core::hints::spin_loop and core::sync::spin_loop_hint --- src/libcore/hint.rs | 27 ++++++++++++++++++++------- src/libcore/sync/atomic.rs | 27 ++++++++++++++++++++------- 2 files changed, 40 insertions(+), 14 deletions(-) diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index d1ccc148654..7d2006e03c4 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -50,15 +50,28 @@ pub unsafe fn unreachable_unchecked() -> ! { intrinsics::unreachable() } -/// Save power or switch hyperthreads in a busy-wait spin-loop. +/// Signals the processor that it is entering a busy-wait spin-loop. /// -/// 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. +/// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving +/// power or switching hyper-threads. /// -/// On some platforms this function may not do anything at all. +/// This function is different than [`std::thread::yield_now`] which directly yields to the +/// system's scheduler, whereas `spin_loop` 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` 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 #[inline] #[unstable(feature = "renamed_spin_loop", issue = "55002")] pub fn spin_loop() { diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 04a49d25301..26b59969e18 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -124,15 +124,28 @@ use hint::spin_loop; -/// Save power or switch hyperthreads in a busy-wait spin-loop. +/// Signals the processor that it is entering a busy-wait spin-loop. /// -/// 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. +/// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving +/// power or switching hyper-threads. /// -/// On some platforms this function may not do anything at all. +/// 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 #[inline] #[stable(feature = "spin_loop_hint", since = "1.24.0")] pub fn spin_loop_hint() { From becee90cfd9f174ed050c1d4b366fd13d89f1913 Mon Sep 17 00:00:00 2001 From: Christian Date: Wed, 3 Apr 2019 15:47:38 +0200 Subject: [PATCH 2/2] Updated the reference in core::hint::spin_loop to the correct relative path. --- src/libcore/hint.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index 7d2006e03c4..d43e6c49f4c 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -71,7 +71,7 @@ pub unsafe fn unreachable_unchecked() -> ! { /// **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 +/// [`std::thread::yield_now`]: ../../std/thread/fn.yield_now.html #[inline] #[unstable(feature = "renamed_spin_loop", issue = "55002")] pub fn spin_loop() {