From 7d45ce0a1e9f73b33a3ad7464724b6f38db90a1f Mon Sep 17 00:00:00 2001 From: Kestrer Date: Thu, 17 Mar 2022 19:03:29 +0000 Subject: [PATCH 1/2] Explain the atomic orderings used in race --- src/race.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/race.rs b/src/race.rs index 3576420..1c81625 100644 --- a/src/race.rs +++ b/src/race.rs @@ -5,6 +5,18 @@ //! them stores the result. //! //! This module does not require `std` feature. +//! +//! # Atomic orderings +//! +//! All types in this module use `Acquire` and `Release` +//! [atomic orderings](Ordering) for all their operations. While this is not +//! strictly necessary, it is useful for users as it allows them to be certain +//! that after `get` or `get_or_init` returns on one thread, any side-effects +//! caused by the setter thread prior to them calling `set` or `get_or_init` +//! will be made visible to that thread; without it, it's possible for it to +//! appear as if they haven't happened yet from the getter thread's perspective. +//! This is an acceptable tradeoff to make since `Acquire` and `Release` have +//! very little performance overhead on most architectures versus `Relaxed`. #[cfg(feature = "atomic-polyfill")] use atomic_polyfill as atomic; From 580fb726679a7d3b233c631f4cc05725596ccf27 Mon Sep 17 00:00:00 2001 From: Kestrer Date: Fri, 18 Mar 2022 17:07:38 +0000 Subject: [PATCH 2/2] Note that Acquire/Release is necessary in OnceBox --- src/race.rs | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/src/race.rs b/src/race.rs index 1c81625..e83e0b9 100644 --- a/src/race.rs +++ b/src/race.rs @@ -10,13 +10,14 @@ //! //! All types in this module use `Acquire` and `Release` //! [atomic orderings](Ordering) for all their operations. While this is not -//! strictly necessary, it is useful for users as it allows them to be certain -//! that after `get` or `get_or_init` returns on one thread, any side-effects -//! caused by the setter thread prior to them calling `set` or `get_or_init` -//! will be made visible to that thread; without it, it's possible for it to -//! appear as if they haven't happened yet from the getter thread's perspective. -//! This is an acceptable tradeoff to make since `Acquire` and `Release` have -//! very little performance overhead on most architectures versus `Relaxed`. +//! strictly necessary for types other than `OnceBox`, it is useful for users as +//! it allows them to be certain that after `get` or `get_or_init` returns on +//! one thread, any side-effects caused by the setter thread prior to them +//! calling `set` or `get_or_init` will be made visible to that thread; without +//! it, it's possible for it to appear as if they haven't happened yet from the +//! getter thread's perspective. This is an acceptable tradeoff to make since +//! `Acquire` and `Release` have very little performance overhead on most +//! architectures versus `Relaxed`. #[cfg(feature = "atomic-polyfill")] use atomic_polyfill as atomic;