Rewrite docs for fetch_update for clarity #136036

hkBst · 2025-01-25T02:32:33Z

In particular also uses the same names for the orderings as compare_exchange does to reduce confusion as per #89116.

rustbot · 2025-01-25T02:32:40Z

rustbot has assigned @thomcc.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

hkBst · 2025-01-26T11:33:01Z

Once the proposed text replacement is approved, I will copy it to the other two places that define fetch_update.

bors · 2025-01-28T18:15:26Z

☔ The latest upstream changes (presumably #136185) made this pull request unmergeable. Please resolve the merge conflicts.

In particular also uses the same names for the orderings as compare_exchange does to reduce confusion as per rust-lang#89116.

Sky9x · 2025-01-29T20:06:11Z

library/core/src/sync/atomic.rs

                                   mut f: F) -> Result<$int_type, $int_type>
            where F: FnMut($int_type) -> Option<$int_type> {
-                let mut prev = self.load(fetch_order);
+                let mut prev = self.load(failure);


perhaps a comment explaining why we are loading with the 'failure' order could be added here?

I'm not sold on this particular naming, but this change tries to bring this into line with compare_exchange's use of the terms. It explains the terms like this: "success describes the required ordering for the read-modify-write operation that takes place if the comparison with current succeeds. failure describes the required ordering for the load operation that takes place when the comparison fails.". Perhaps update_order and load_order are better terms?

The existing set_order and fetch_order are probably fine. It would indeed seem weird to immediately load a value using failure.

Sky9x · 2025-01-29T20:08:06Z

library/core/src/sync/atomic.rs

+            /// Note: susceptible to the [ABA Problem](https://en.wikipedia.org/wiki/ABA_problem).
            ///
            /// **Note**: This method is only available on platforms that support atomic operations on
            #[doc = concat!("[`", $s_int_type, "`].")]
            ///
-            /// # Considerations
-            ///
-            /// This method is not magic; it is not provided by the hardware.
-            /// It is implemented in terms of
-            #[doc = concat!("[`", stringify!($atomic_type), "::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
-            ///


Why was this changed? IMO the longer version is better.

The implementation using compare_exchange_weak is now explicitly described. This makes it unnecessary to say it is not magic, because that is now obvious. Also, users are more likely to look at the docs for compare_exchange_weak. That leaves the "in particular ... ABA problem", which I've shortened to its core, which is that this method is "susceptible to the ABA Problem".

The explicit description of how the implementation uses compare_exchange_weak is also why I removed the copy of the description of the constraints on the memory orderings which comes directly from using compare_exchange_weak. Thanks for reviewing!

Agreed with @Sky9x, this section should remain. It's one thing to explain that this uses compare_exchange_weak, another thing to confirm that it doesn't somehow do some tricks to avoid compare_exchange_weak's limitations.

Plus I have definitely seen this specific section get linked around.

bors · 2025-06-13T08:34:09Z

☔ The latest upstream changes (presumably #142432) made this pull request unmergeable. Please resolve the merge conflicts.

tgross35 · 2025-06-16T03:25:33Z

library/core/src/sync/atomic.rs

+            /// Loads the current value, applies a closure to it, and optionally tries to store a new value.
+            /// If the closure ever returns None, this method will immediately return `Err(current value)`.


This needs an empty line between the two sentences here; otherwise rustdoc will treat the entire section here as the summary line.

tgross35 · 2025-06-16T03:32:12Z

library/core/src/sync/atomic.rs

+            /// If the closure returns Some(new value), then this method calls
+            #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange_weak`]")]
+            /// to try to store the new value.
+            /// If storing a new value fails, because another thread changed the current value,


Suggested change

/// If storing a new value fails, because another thread changed the current value,

/// If storing a new value fails (due to another thread changing the current value)

Suggested reword to avoid using comma+"because" for an interjection

tgross35 · 2025-06-16T03:49:33Z

library/core/src/sync/atomic.rs

+            /// then the given closure will be called again on the new current value
+            /// (that was just returned by compare_exchange_weak),
+            /// until either the closure returns None,
+            /// or compare_exchange_weak succeeds in storing a new value.
+            /// Returns `Ok(previous value)` if it ever succeeds in storing a new value.
+            /// Takes a success and a failure [`Ordering`] to pass on to compare_exchange_weak,
+            /// and also uses the failure ordering for the initial load.


Suggested change

/// then the given closure will be called again on the new current value

/// (that was just returned by compare_exchange_weak),

/// until either the closure returns None,

/// or compare_exchange_weak succeeds in storing a new value.

/// Returns `Ok(previous value)` if it ever succeeds in storing a new value.

/// Takes a success and a failure [`Ordering`] to pass on to compare_exchange_weak,

/// and also uses the failure ordering for the initial load.

/// then the given closure will be called again on the new current value,

/// which was just returned by `compare_exchange_weak`.

/// This will repeat until either the closure returns None,

/// or `compare_exchange_weak` succeeds in storing a new value. The return value is

/// `Ok(previous value)` if a new value was ever successfully stored, otherwise

/// `Err(current_value)`

///

/// Takes a success and a failure [`Ordering`] to pass on to `compare_exchange_weak`,

/// and also uses the failure ordering for the initial load.

Few suggestions:

Split the long sentence and make the CEW call part of the main flow.

Mention the Err condition right next to Ok.

Split the ordering discussion to a new paragraph.

compare_exchange_weak needs backticks

Also please make sure to rewrap doc comments to 100 chars before merge, or as far as is possible with the scattered #[doc] attributes.

tgross35 · 2025-06-16T04:00:50Z

library/core/src/sync/atomic.rs

+            /// Note: susceptible to the [ABA Problem](https://en.wikipedia.org/wiki/ABA_problem).
            ///
            /// **Note**: This method is only available on platforms that support atomic operations on
            #[doc = concat!("[`", $s_int_type, "`].")]
            ///
-            /// # Considerations
-            ///
-            /// This method is not magic; it is not provided by the hardware.
-            /// It is implemented in terms of
-            #[doc = concat!("[`", stringify!($atomic_type), "::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
-            ///


Agreed with @Sky9x, this section should remain. It's one thing to explain that this uses compare_exchange_weak, another thing to confirm that it doesn't somehow do some tricks to avoid compare_exchange_weak's limitations.

Plus I have definitely seen this specific section get linked around.

tgross35 · 2025-06-16T04:04:56Z

library/core/src/sync/atomic.rs

                while let Some(next) = f(prev) {
-                    match self.compare_exchange_weak(prev, next, set_order, fetch_order) {
+                    match self.compare_exchange_weak(prev, next, success, failure) {
                        x @ Ok(_) => return x,
                        Err(next_prev) => prev = next_prev
                    }


Please make sure to update update and try_update as well once this is closer to ready #135894

tgross35 · 2025-06-16T04:11:54Z

library/core/src/sync/atomic.rs

                                   mut f: F) -> Result<$int_type, $int_type>
            where F: FnMut($int_type) -> Option<$int_type> {
-                let mut prev = self.load(fetch_order);
+                let mut prev = self.load(failure);


The existing set_order and fetch_order are probably fine. It would indeed seem weird to immediately load a value using failure.

hkBst · 2025-06-16T04:33:55Z

@tgross35, thanks for reviewing! I'll look at each of your points soon.

rustbot assigned thomcc Jan 25, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jan 25, 2025

This comment has been minimized.

Sign in to view

hkBst force-pushed the patch-26 branch from 772fc85 to bbe765e Compare January 26, 2025 11:27

Rewrite docs for fetch_update for clarity

1a0d867

In particular also uses the same names for the orderings as compare_exchange does to reduce confusion as per rust-lang#89116.

hkBst force-pushed the patch-26 branch from bbe765e to 1a0d867 Compare January 28, 2025 18:25

hkBst marked this pull request as ready for review January 29, 2025 05:39

Sky9x reviewed Jan 29, 2025

View reviewed changes

hkBst requested a review from Sky9x February 5, 2025 13:27

tgross35 requested changes Jun 16, 2025

View reviewed changes

		/// Loads the current value, applies a closure to it, and optionally tries to store a new value.
		/// If the closure ever returns None, this method will immediately return `Err(current value)`.

	/// If storing a new value fails, because another thread changed the current value,
	/// If storing a new value fails (due to another thread changing the current value)

Rewrite docs for fetch_update for clarity #136036

Are you sure you want to change the base?

Rewrite docs for fetch_update for clarity #136036

Conversation

hkBst commented Jan 25, 2025

Uh oh!

rustbot commented Jan 25, 2025

Uh oh!

This comment has been minimized.

hkBst commented Jan 26, 2025

Uh oh!

bors commented Jan 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hkBst Jan 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bors commented Jun 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hkBst commented Jun 16, 2025

Uh oh!

Uh oh!

hkBst Jan 30, 2025 •

edited

Loading