Skip to content

Commit f985f24

Browse files
authored
Rollup merge of #59664 - DevQps:improve-yield-spinlock-docs, r=alexcrichton
Updated the documentation of spin_loop and spin_loop_hint # Description - Updated the description of `core::hints::spin_loop` - Updated the description of `core::async::spin_loop_hint` Both documentation is rewritten to better reflect when one should prefer using a busy-wait spin-loop (and the `spin_loop` and `spin_loop_hint` functions) over `yield_now`. It also dives a little bit deeper on what the function actually does. closes #55418
2 parents f35aed8 + becee90 commit f985f24

File tree

2 files changed

+40
-14
lines changed

2 files changed

+40
-14
lines changed

src/libcore/hint.rs

+20-7
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,28 @@ pub unsafe fn unreachable_unchecked() -> ! {
5050
intrinsics::unreachable()
5151
}
5252

53-
/// Save power or switch hyperthreads in a busy-wait spin-loop.
53+
/// Signals the processor that it is entering a busy-wait spin-loop.
5454
///
55-
/// This function is deliberately more primitive than
56-
/// [`std::thread::yield_now`](../../std/thread/fn.yield_now.html) and
57-
/// does not directly yield to the system's scheduler.
58-
/// In some cases it might be useful to use a combination of both functions.
59-
/// Careful benchmarking is advised.
55+
/// Upon receiving spin-loop signal the processor can optimize its behavior by, for example, saving
56+
/// power or switching hyper-threads.
6057
///
61-
/// On some platforms this function may not do anything at all.
58+
/// This function is different than [`std::thread::yield_now`] which directly yields to the
59+
/// system's scheduler, whereas `spin_loop` only signals the processor that it is entering a
60+
/// busy-wait spin-loop without yielding control to the system's scheduler.
61+
///
62+
/// Using a busy-wait spin-loop with `spin_loop` is ideally used in situations where a
63+
/// contended lock is held by another thread executed on a different CPU and where the waiting
64+
/// times are relatively small. Because entering busy-wait spin-loop does not trigger the system's
65+
/// scheduler, no overhead for switching threads occurs. However, if the thread holding the
66+
/// contended lock is running on the same CPU, the spin-loop is likely to occupy an entire CPU slice
67+
/// before switching to the thread that holds the lock. If the contending lock is held by a thread
68+
/// on the same CPU or if the waiting times for acquiring the lock are longer, it is often better to
69+
/// use [`std::thread::yield_now`].
70+
///
71+
/// **Note**: On platforms that do not support receiving spin-loop hints this function does not
72+
/// do anything at all.
73+
///
74+
/// [`std::thread::yield_now`]: ../../std/thread/fn.yield_now.html
6275
#[inline]
6376
#[unstable(feature = "renamed_spin_loop", issue = "55002")]
6477
pub fn spin_loop() {

src/libcore/sync/atomic.rs

+20-7
Original file line numberDiff line numberDiff line change
@@ -124,15 +124,28 @@ use fmt;
124124

125125
use hint::spin_loop;
126126

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

0 commit comments

Comments
 (0)