Skip to content

Commit

Permalink
Remove wrong advice about spin locks from spin_loop_hint docs
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
matklad committed Jan 2, 2020
1 parent 0ec3706 commit 4d04b0b
Showing 1 changed file with 2 additions and 10 deletions.
12 changes: 2 additions & 10 deletions src/libcore/sync/atomic.rs
Original file line number Diff line number Diff line change
Expand Up @@ -134,16 +134,8 @@ use crate::hint::spin_loop;
/// 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.
///
/// 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.
/// 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**: On platforms that do not support receiving spin-loop hints this function does not
/// do anything at all.
Expand Down

0 comments on commit 4d04b0b

Please sign in to comment.