From b25eeef88d55a412c0e0bec7c0989d5a7969f195 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Sun, 5 Jan 2020 20:06:52 +0100 Subject: [PATCH] Add more nuanced advice about spin_loop_hint --- src/libcore/sync/atomic.rs | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index ba41cd2b7a08e..fae95ca5cdb36 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -134,8 +134,10 @@ 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. /// -/// 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. +/// A common use case for `spin_loop_hint` is implementing bounded optimistic spinning in a CAS +/// loop in synchronization primitives. To avoid problems like priority inversion, it is strongly +/// recommended that the spin loop is terminated after a finite amount of iterations and an +/// appropriate blocking syscall is made. /// /// **Note**: On platforms that do not support receiving spin-loop hints this function does not /// do anything at all.