From 356b4c81a04d1db70621949b25c0cc80d5c94b8e Mon Sep 17 00:00:00 2001 From: Arno Haase Date: Tue, 10 Sep 2019 14:03:31 +0200 Subject: [PATCH 1/5] documentation enhancement for 'spin loop hint': replace 'CPU' with 'CPU or core' --- src/libcore/hint.rs | 6 +++--- src/libcore/sync/atomic.rs | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index 6439fa0e0c8b8..9a581d90cc205 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -59,12 +59,12 @@ pub unsafe fn unreachable_unchecked() -> ! { /// 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 +/// contended lock is held by another thread executed on a different CPU or core 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 +/// contended lock is running on the same CPU or core, 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 +/// on the same CPU or thread 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 diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 8dfb19fa03296..bdd045f75651e 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -134,12 +134,12 @@ use crate::hint::spin_loop; /// 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 +/// contended lock is held by another thread executed on a different CPU or core 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 +/// contended lock is running on the same CPU or core, 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 +/// on the same CPU or core 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 From 66e4b3447110bb06930f4a606e5a47c55ca73a8a Mon Sep 17 00:00:00 2001 From: Arno Haase Date: Tue, 10 Sep 2019 14:04:52 +0200 Subject: [PATCH 2/5] typo fix --- 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 9a581d90cc205..861ad6b54201e 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -64,7 +64,7 @@ pub unsafe fn unreachable_unchecked() -> ! { /// scheduler, no overhead for switching threads occurs. However, if the thread holding the /// contended lock is running on the same CPU or core, 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 thread or if the waiting times for acquiring the lock are longer, it is often better to +/// on the same CPU or core 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 From 51c49e257322babe0426327102357877a9015f4d Mon Sep 17 00:00:00 2001 From: Arno Haase Date: Tue, 10 Sep 2019 14:25:40 +0200 Subject: [PATCH 3/5] fixed linter error --- src/libcore/hint.rs | 14 +++++++------- src/libcore/sync/atomic.rs | 14 +++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index 861ad6b54201e..53c576abb7998 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -59,13 +59,13 @@ pub unsafe fn unreachable_unchecked() -> ! { /// 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 or core 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 or core, 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 core or if the waiting times for acquiring the lock are longer, it is often better to -/// use [`std::thread::yield_now`]. +/// contended lock is held by another thread executed on a different CPU or core 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 or core, 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 core 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. diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index bdd045f75651e..38339996090b1 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -134,13 +134,13 @@ use crate::hint::spin_loop; /// 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 or core 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 or core, 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 core or if the waiting times for acquiring the lock are longer, it is often better to -/// use [`std::thread::yield_now`]. +/// contended lock is held by another thread executed on a different CPU or core 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 or core, 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 core 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. From f4f136e67bedc098bea5e5dce6b286611908355b Mon Sep 17 00:00:00 2001 From: Arno Haase Date: Tue, 17 Sep 2019 12:09:07 +0200 Subject: [PATCH 4/5] newly phrased documentation for spin loop hints --- src/libcore/hint.rs | 22 +++++----------------- src/libcore/sync/atomic.rs | 27 +++++++++++++++------------ 2 files changed, 20 insertions(+), 29 deletions(-) diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index 53c576abb7998..3ea8b31fda6d0 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -49,28 +49,16 @@ pub unsafe fn unreachable_unchecked() -> ! { intrinsics::unreachable() } -/// Signals the processor that it is entering a busy-wait spin-loop. +/// Emits a machine instruction hinting to the processor that it is running in busy-wait +/// spin-loop ("spin lock"). /// -/// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving -/// power or switching hyper-threads. -/// -/// 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 or core 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 or core, 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 core or if the waiting times for acquiring the lock are longer, it -/// is often better to use [`std::thread::yield_now`]. +/// For a discussion of different locking strategies and their trade-offs, see +/// [`core::sync::atomic::spin_loop_hint`]. /// /// **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 +/// [`core::sync::atomic::spin_loop_hint`]: ./sync/atomic/fn.spin_loop_hint.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 38339996090b1..63ee9a42a0f72 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -124,28 +124,31 @@ use crate::fmt; use crate::hint::spin_loop; -/// Signals the processor that it is entering a busy-wait spin-loop. +/// Signals the processor that it is inside a busy-wait spin-loop ("spin lock"). /// /// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving /// power or switching hyper-threads. /// -/// 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. +/// This function is different from [`std::thread::yield_now`] which directly yields to the +/// system's scheduler, whereas `spin_loop_hint` does not interact with the operating system. /// -/// 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 or core 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 or core, 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 core or if the waiting times for acquiring the lock are longer, it -/// is often better to use [`std::thread::yield_now`]. +/// Spin locks can be very efficient for short lock durations because they do not involve context +/// switches or interaction with the operating system. For long lock durations they become wasteful +/// however because they use CPU cycles for the entire lock duration, and using a +/// [`std::sync::Mutex`] is likely the better approach. If actively spinning for a long time is +/// required, e.g. because code polls a non-blocking API, calling [`std::thread::yield_now`] +/// or [`std::thread::sleep`] may be the best option. +/// +/// **Note**: Spin locks are based on the underlying assumption that another thread will release +/// the lock 'soon'. In order for this to work, that other thread must run on a different CPU or +/// core (at least potentially). Spin locks do not work efficiently on single CPU / core platforms. /// /// **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::sleep`]: ../../../std/thread/fn.sleep.html +/// [`std::sync::Mutex`]: ../../../std/sync/Mutex.html #[inline] #[stable(feature = "spin_loop_hint", since = "1.24.0")] pub fn spin_loop_hint() { From eb48b5d983fde79ab3595f250871116ee650c5e9 Mon Sep 17 00:00:00 2001 From: Arno Haase Date: Wed, 18 Sep 2019 12:31:34 +0200 Subject: [PATCH 5/5] broken hyperlinks in documentation --- src/libcore/hint.rs | 2 +- src/libcore/sync/atomic.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/libcore/hint.rs b/src/libcore/hint.rs index 3ea8b31fda6d0..ee4be6c915119 100644 --- a/src/libcore/hint.rs +++ b/src/libcore/hint.rs @@ -58,7 +58,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. /// -/// [`core::sync::atomic::spin_loop_hint`]: ./sync/atomic/fn.spin_loop_hint.html +/// [`core::sync::atomic::spin_loop_hint`]: ../sync/atomic/fn.spin_loop_hint.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 63ee9a42a0f72..ab5af5682c180 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -148,7 +148,7 @@ use crate::hint::spin_loop; /// /// [`std::thread::yield_now`]: ../../../std/thread/fn.yield_now.html /// [`std::thread::sleep`]: ../../../std/thread/fn.sleep.html -/// [`std::sync::Mutex`]: ../../../std/sync/Mutex.html +/// [`std::sync::Mutex`]: ../../../std/sync/struct.Mutex.html #[inline] #[stable(feature = "spin_loop_hint", since = "1.24.0")] pub fn spin_loop_hint() {