rust/library
Matthias Krüger 764be85223
Rollup merge of #142252 - fu5ha:doc-cas-ops, r=ibraheemdev
Improve clarity of `core::sync::atomic` docs about "Considerations" in regards to CAS operations

## Motivation

The existing documentation for atomic `fetch_update` (and other similar methods) has a section that reads like so:

> ### Considerations
> This method is not magic; it is not provided by the hardware. It is implemented in
> terms of `AtomicBlah::compare_exchange_weak`, and suffers from the same drawbacks.
> In particular, this method will not circumvent the [ABA Problem].
>
> [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem

The wording here seems to imply that the drawbacks being discusses are caused by the *`weak` version* of `compare_exchange`, and that one may avoid those drawbacks by using `compare_exchange` instead. Indeed, a conversation in the `#dark-arts` channel on the Rust community discord based on this interpretation led to this PR.

In reality, the drawbacks are inherent to implementing such an operation based on *any* compare-and-swap style operation, as opposed to an [LL,SC](https://en.wikipedia.org/wiki/Load-link/store-conditional) operation, and they apply equally to `compare_exchange` and `compare_exchange_weak` as well.

## Changes

- Rewords existing Considerations section on `fetch_update` and friends to make clear that the limitations are inherent to an implementation based on any CAS operation, rather than the weak version of `compare_exchange` in particular. New version:

> ### Considerations
>
> This method is not magic; it is not provided by the hardware, and does not act like a
> critical section or mutex.
>
> It is implemented on top of an atomic [compare-and-swap operation], and thus is subject to
> the usual drawbacks of CAS operations. In particular, be careful of the [ABA problem]
> if this atomic integer is an index or more generally if knowledge of only the *bitwise value*
> of the atomic is not in and of itself sufficient to ensure any required preconditions.
>
> [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
> [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap

- Add Considerations to `compare_exchange` and `compare_exchange_weak` which details similar considerations and when they may be relevant. New version:

> ### Considerations
>
> `compare_exchange` is a [compare-and-swap operation] and thus exhibits the usual downsides
> of CAS operations. In particular, a load of the value followed by a successful
> `compare_exchange` with the previous load *does not ensure* that other threads have not
> changed the value in the interim. This is usually important when the *equality* check in
> the `compare_exchange` is being used to check the *identity* of a value, but equality
> does not necessarily imply identity. In this case, `compare_exchange` can lead to the
> [ABA problem].
>
> [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem
> [compare-and-swap operation]: https://en.wikipedia.org/wiki/Compare-and-swap
2025-06-12 20:03:37 +02:00
..
alloc Rollup merge of #142238 - RalfJung:nonnull_provenance, r=workingjubilee 2025-06-09 12:17:55 -05:00
alloctests Rollup merge of #138016 - nwoods-cimpress:slice_chunkby_clone, r=dtolnay 2025-06-12 20:03:34 +02:00
backtrace@6c882eb119 Fix backtrace for cygwin 2025-05-07 13:08:19 +08:00
compiler-builtins indent the probestack inline assembly 2025-06-10 10:09:00 +02:00
core Rollup merge of #142252 - fu5ha:doc-cas-ops, r=ibraheemdev 2025-06-12 20:03:37 +02:00
coretests Auto merge of #136594 - pascaldekloe:fmt-int128, r=tgross35 2025-06-12 01:02:55 +00:00
panic_abort Use the in-tree compiler-builtins 2025-06-08 02:36:58 +00:00
panic_unwind Rollup merge of #141993 - tgross35:use-in-tree-builtins, r=bjorn3 2025-06-09 12:17:53 -05:00
portable-simd Merge commit 'c14f2fc3eb' into sync-from-portable-simd-2025-03-19 2025-03-19 00:58:47 -04:00
proc_macro Do not get proc_macro from the sysroot in rustc 2025-05-27 15:49:28 +00:00
profiler_builtins Fix profiler_builtins build script to handle full path to profiler lib 2025-04-11 16:57:38 +02:00
rtstartup Revert changes for rtstartup 2025-03-10 21:23:31 +08:00
rustc-std-workspace-alloc Migrated the rustc-std-workspace crates to Rust 2024 2025-03-11 09:46:35 -07:00
rustc-std-workspace-core Use the in-tree compiler-builtins 2025-06-08 02:36:58 +00:00
rustc-std-workspace-std Migrated the rustc-std-workspace crates to Rust 2024 2025-03-11 09:46:35 -07:00
std Rollup merge of #142102 - kiseitai3:141714_stdin_read_to_string_docs, r=tgross35 2025-06-10 16:54:49 +02:00
stdarch@5c1c436524 Update stdarch submodule 2025-06-03 18:54:56 +05:30
sysroot Update stdarch 2025-05-01 20:01:43 +05:30
test Add new test_main_with_exit_callback public function in libtest to allow a callback to be called before exiting 2025-05-06 18:17:48 +02:00
unwind Rollup merge of #141993 - tgross35:use-in-tree-builtins, r=bjorn3 2025-06-09 12:17:53 -05:00
windows_targets Fix backtrace for cygwin 2025-05-07 13:08:19 +08:00
Cargo.lock cargo update 2025-06-11 21:11:54 -04:00
Cargo.toml Use the in-tree compiler-builtins 2025-06-08 02:36:58 +00:00