std::thread::yield_now() example is lacking.

[dev-ardi]

Location

rust/library/std/src/thread/mod.rs:755

/// # Examples
///
/// ```
/// use std::thread;
///
/// thread::yield_now();
/// ```

Summary

It's not great, ideally it should show a mostly real use case.

It should maybe hint that this should not be used directly to create spin loops without first considering std::hint::spin_loop

[Noratrieb]

It should not be used to create spin loops, no one should ever create spinloops when an OS scheduler is present

[dev-ardi]

no one should ever create spinloops when an OS scheduler is present

You could consider a CAS loop to be a spin loop. Also I don't think that that's true, an approach to this is to spin lock with spin_lock() and after a set number of iterations use yield_now to avoid being set to higher prio.

Spin locks are used sometimes in userland code in some apps like game engines.

[the8472]

You might be thinking of hint::spin_loop? CAS loops are waiting on a memory location, so they can use futexes to tell the kernel what they're waiting on and don't need thread::yield_now for that and use spin_loop to briefly wait in userspace.

to avoid being set to higher prio

Does waitonaddress do priority inheritance? On linux futexes can opt in/out of PI.

Anyway, even if that's an issue it seems like a highly specific reason that doesn't seem appropriate for a code example.

We do have uses of yield_now in std too, but that's often a "might as well try before we give up" situation, not good code.

rust/library/std/src/sys/pal/windows/fs/remove_dir_all.rs

Lines 153 to 172 in a92c3cf

	/// A simple retry loop that keeps running `f` while it fails with the given
	/// error code or until `MAX_RETRIES` is reached.
	fn retry<T: PartialEq>(
	mut f: impl FnMut() -> Result<T, WinError>,
	ignore: WinError,
	) -> Result<T, WinError> {
	let mut i = MAX_RETRIES;
	loop {
	i -= 1;
	if i == 0 {
	return f();
	} else {
	let result = f();
	if result != Err(ignore) {
	return result;
	}
	}
	thread::yield_now();
	}
	}