Tracking issue for hint::spin_loop (renamed sync::atomic::spin_loop_hint)

[Clar Fon]

Now that we have at least one thing in std::hint it makes sense to move this to std::hint::spin_loop.

---

EDIT (@KodrAus)

Before stabilisation:

• Decide on new function name (hint::spin_loop or spin_loop_hint)

Stabilisation/deprecation:

• Stabilise renamed_spin_loop feature [#76097]
• Deprecate the sync::atomic::spin_loop_hint function

[gnzlbg]

spin_loop currently invokes undefined behavior on x86 and x86_64 targets without SSE2. One of those targets is tier-1: i686-apple-darwin.

[Hanna Kruppe]

Are you sure? The target spec for that sets the cpu to Yonah, which has SSE2.

[gnzlbg]

@rkruppe if that was fixed we should close: #53423

[gnzlbg]

@rkruppe indeed, that's fixed, I've closed that issue.

[Clar Fon]

Note that this isn't a tracking issue for the function itself; it's already stable and any bugs/qualms are reported separately. This is just for the renaming of it.

[zopsicle]

If this routine is moved to std::hint then the documentation of std::hint should be updated as well. It currently reads:

Hints to compiler that affects how code should be emitted or optimized.

Pause instruction is a hint to the CPU, not to the compiler.

[Clar Fon]

I agree; it should be changed to "compiler and/or CPU".

[Ashley Mannix]

It's been a few years since this landed, so in an effort to un-kitchen-sink the sync module I think we should:

• Inline the comments on std::sync::atomic::spin_loop_hint onto std::hint::spin_loop and point the docs to std::hint::spin_loop instead
• Add a trivial busy-loop example that demonstrates how we want you to call it as hint::spin_loop
• Update the docs for the std::hint module to note that hints may be compile time or runtime
• Stabilize std::hint::spin_loop under that name
• Deprecate std::sync::atomic::spin_loop_hint

@rfcbot fcp merge

This proposes stabilizing the following API:

pub mod hint {
    pub fn spin_loop();
}

And deprecating the following API:

pub mod sync {
    pub mod atomic {
        pub fn spin_loop_hint();
    }
}

[Rust RFC bot]

Team member @KodrAus has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @KodrAus
• @SimonSapin
• @dtolnay
• @sfackler
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[Rust RFC bot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[Jacob Lifshay]

@gnzlbg

spin_loop currently invokes undefined behavior on x86 and x86_64 targets without SSE2.

Assuming LLVM generates the x86 pause instruction, it actually has defined behavior on pre-SSE2 processors:
https://www.felixcloutier.com/x86/pause

This instruction was introduced in the Pentium 4 processors, but is backward compatible with all IA-32 processors. In earlier IA-32 processors, the PAUSE instruction operates like a NOP instruction. The Pentium 4 and Intel Xeon processors implement the PAUSE instruction as a delay. The delay is finite and can be zero for some processors. This instruction does not change the architectural state of the processor (that is, it performs essentially a delaying no-op operation).

it disassembles to a rep nop instruction, where the rep prefix is ignored by processors that don't understand the pause instruction.

[Clar Fon]

One (not required for stabilisation) thing that may also useful to mention is that spin_loop can also be used for embedded contexts, although I don't have any useful examples that aren't antequated x86 OS code, so, I'm sure that someone more active with embedded stuff can comment.

Essentially, there are times where you can't outright halt the CPU until the next interrupt and you also have to wait for a condition to be met, and because you are the scheduler, obviously you can't yield to the scheduler.

[srrrse]

Let's have at least 1 release cycle between stabilizing hint::spin_loop and deprecating atomic::spin_loop_hint, so proactive people can have 6 weeks to make the change at their own convenience without getting a warning?

[Rust RFC bot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

The RFC will be merged soon.

[Gabriel Smith]

I don't think this should be closed yet seeing as the depreciation has not been done.

[Noah Lev]

Reopening to track deprecation of sync::atomic::spin_loop_hint.

[Ashley Mannix]

Now that atomic::spin_loop_hint is deprecated I'll go ahead and close this tracking issue.