`// ORDERING: ...` comment for atomic operations

What it does

Similar to // SAFETY: ..., // PANIC: ... and // CAST: ... comments, but for atomic operations that use one or more Orderings.

Note that in the Linux kernel we use a custom implementation of atomics, so we should probably pass a list of functions/methods/... to warn about, similar to // PANIC: ....

More generally, we could consider an implementation that warns on functions/methods that take Ordering parameters unless opt-ed out. But just the list as for // PANIC: ... sounds good enough, and perhaps it makes sense to instead generalize that lint to allow the user to customize a map of TAG-> list of methods that require a comment.

That is, we would like code to look like:

// ORDERING: Relaxed is fine because we don't expect synchronization here.
let old = self.init.xchg(1, Relaxed);

In other words, like undocumented_unsafe_blocks, but for atomic operations.

In addition, there would be a dual lint to detect unnecessary comments: https://github.com/rust-lang/rust-clippy/issues/16074.

Cc: @blyxyas @hcbarker @fbq

Advantage

The advantages are very similar to the ones we have seen from applying the // SAFETY: ... convention:

• Atomic operations get documented better, i.e. the reason a particular Ordering is used must be explained.

• It gives some pause to developers when picking an Ordering.

These advantages also mean review time (and thus maintainers' workload) gets reduced, since reviewers will have an easier time following the rationale behind the Orderings picked.

Drawbacks

No response

Example

let old = self.init.xchg(1, Relaxed);

Should be written as:

// ORDERING: Relaxed is fine because we don't expect synchronization here.
let old = self.init.xchg(1, Relaxed);

Comparison with existing lints

No response

Additional Context

Please see the "Additional context" for // PANIC: ... on https://github.com/rust-lang/rust-clippy/issues/15895.

Start by reading the additional context for // PANIC: ... in issue 15895 and compare the proposed dual lint in issue 16074. Define the supported atomic functions or methods, the ORDERING comment behavior, and whether configurable tag-to-method mappings are in scope. Done means the desired lint behavior and its boundaries are agreed and documented.