Skip to content

Commit 17b90c1

Browse files
authored
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
2 parents 6614229 + 4c5679f commit 17b90c1

File tree

0 file changed

+0
-0
lines changed

    0 file changed

    +0
    -0
    lines changed

    0 commit comments

    Comments
     (0)