Struct surge_wavetable::imports::imports::imports::imports::AtomicF32

#[repr(transparent)]
pub struct AtomicF32(_);

A floating point type which can be safely shared between threads.

This type has the same in-memory representation as the underlying floating point type, f32.

See the module documentation for core::sync::atomic for information about the portability of various atomics (this one is mostly as portable as AtomicU32, with the caveat that we additionally that the platform support 32-bit floats).

Example

The intended use case is situations like this:

static DELTA_TIME: AtomicF32 = AtomicF32::new(1.0);

// In some main simulation loop:
DELTA_TIME.store(compute_delta_time(), Ordering::Release);

// elsewhere, perhaps on other threads:
let dt = DELTA_TIME.load(Ordering::Acquire);
// Use `dt` to compute simulation...

As well as any other cases where use of locking would be too substantial of overhead.

Note that when used like this (with Acquire and Release orderings), on x86_64 this compiles to the same code as you would get from a C++ global, (or a Rust static mut), while offering full synchronization.

(While caveats exist, the cases where you’d need the total order guaranteed by SeqCst for something like AtomicF32 seem very rare).

Implementation

Note: These details are not part of the stability guarantee of this crate, and are subject to change without a semver-breaking change.

Under the hood we use a transparent UnsafeCell<f32>, and cast the &UnsafeCell<f32> to an &AtomicU32 in order to perform atomic operations.

This means that we have the same ABI and layout as f32, and that some operations have a minimal cost (for example: on x86 all operations of equivalent or weaker ordering than Release stores/Acquire loads are essentially equivalent to non-atomic f32).

However, operations like fetch_add are considerably slower than would be the case for integer atomics.

Implementations

impl AtomicF32

pub const fn new(float: f32) -> AtomicF32

Initialize a AtomicF32 from an f32.

Example

Use as a variable

let x = AtomicF32::new(3.0f32);
assert_eq!(x.load(Relaxed), 3.0f32);

Use as a static:

static A_STATIC: AtomicF32 = AtomicF32::new(800.0);
assert_eq!(A_STATIC.load(Relaxed), 800.0);

pub fn get_mut(&mut self) -> &mut f32

Returns a mutable reference to the underlying float.

This is safe because the mutable reference guarantees that no other threads are concurrently accessing the atomic data.

Example

let mut some_float = AtomicF32::new(1.0);
assert_eq!(*some_float.get_mut(), 1.0);
*some_float.get_mut() += 1.0;
assert_eq!(some_float.load(Ordering::SeqCst), 2.0);

pub fn into_inner(self) -> f32

Consumes the atomic and returns the contained value.

This is safe because passing self by value guarantees that no other threads are concurrently accessing the atomic data.

Example

let v = AtomicF32::new(6.0);
assert_eq!(v.into_inner(), 6.0f32);

pub fn load(&self, ordering: Ordering) -> f32

Loads a value from the atomic float.

load takes an Ordering argument which describes the memory ordering of this operation. Possible values are SeqCst, Acquire and Relaxed.

Panics

Panics if ordering is Release or AcqRel.

Example

use atomic_float::AtomicF32;
use std::sync::atomic::Ordering;
let v = AtomicF32::new(22.5);
assert_eq!(v.load(Ordering::SeqCst), 22.5);

pub fn store(&self, value: f32, ordering: Ordering)

Store a value into the atomic float.

store takes an Ordering argument which describes the memory ordering of this operation. Possible values are SeqCst, Release and Relaxed.

Panics

Panics if ordering is Acquire or AcqRel.

Example

use atomic_float::AtomicF32;
use std::sync::atomic::Ordering;
let v = AtomicF32::new(22.5);
assert_eq!(v.load(Ordering::SeqCst), 22.5);
v.store(30.0, Ordering::SeqCst);
assert_eq!(v.load(Ordering::SeqCst), 30.0);

pub fn swap(&self, new_value: f32, ordering: Ordering) -> f32

Stores a value into the atomic float, returning the previous value.

swap takes an Ordering argument which describes the memory ordering of this operation. All ordering modes are possible. Note that using Acquire makes the store part of this operation Relaxed, and using Release makes the load part Relaxed.

Example

use atomic_float::AtomicF32;
use std::sync::atomic::Ordering;
let v = AtomicF32::new(4.5);
assert_eq!(v.swap(100.0, Ordering::Relaxed), 4.5);
assert_eq!(v.load(Ordering::Relaxed), 100.0);

pub fn compare_and_swap(&self, current: f32, new: f32, order: Ordering) -> f32

Stores a value into the atomic float if the current value is bitwise identical to the current value.

The return value is always the previous value. If it is equal to current, then the value was updated.

compare_and_swap also takes an Ordering argument which describes the memory ordering of this operation. Notice that even when using AcqRel, the operation might fail and hence just perform an Acquire load, but not have Release semantics. Using Acquire makes the store part of this operation Relaxed if it happens, and using Release makes the load part Relaxed.

Caveats

As the current must be bitwise identical to the previous value, you should not get the current value using any sort of arithmetic (both because of rounding, and to avoid any situation where -0.0 and +0.0 would be compared). Additionally, on some platforms (WASM and ASM.js currently) LLVM will canonicalize NaNs during loads, which can cause unexpected behavior here — typically in the other direction (two values being unexpectedly equal).

In practice, typical patterns for CaS tend to avoid these issues, but you’re encouraged to avoid relying on the behavior of cas-family APIs in the face of rounding, signed zero, and NaNs.

Example

let v = AtomicF32::new(5.0);
assert_eq!(v.compare_and_swap(5.0, 10.0, Ordering::Relaxed), 5.0);
assert_eq!(v.load(Ordering::Relaxed), 10.0);

assert_eq!(v.compare_and_swap(6.0, 12.0, Ordering::Relaxed), 10.0);
assert_eq!(v.load(Ordering::Relaxed), 10.0);

pub fn compare_exchange(
    &self,
    current: f32,
    new: f32,
    success: Ordering,
    failure: Ordering
) -> Result<f32, f32>

Stores a value into the atomic float if the current value is the bitwise identical as the current value.

The return value is a result indicating whether the new value was written and containing the previous value. On success this value is guaranteed to be bitwise identical to current.

compare_exchange takes two Ordering arguments to describe the memory ordering of this operation. The first describes the required ordering if the operation succeeds while the second describes the required ordering when the operation fails. Using Acquire as success ordering makes the store part of this operation Relaxed, and using Release makes the successful load Relaxed. The failure ordering can only be SeqCst, Acquire or Relaxed and must be equivalent to or weaker than the success ordering.

Notes

Note that in many cases, when while loops where the condition contains a compare_exchange operation are better written to use a compare_exchange_weak in the condition instead (as on weakly ordered platforms like ARM, the compare_exchange operation itself can require a loop to perform).

Caveats

As the current parameter must be bitwise identical to the previous value, you should not get the current value using any sort of arithmetic (both because of rounding, and to avoid any situation where -0.0 and +0.0 would be compared). Additionally, on Wasm, in some cases NaN values have been known to cause problems for non-typical usage of this API. See AtomicF32::as_atomic_bits if performing the compare_exchange on the raw bits of this atomic float would solve an issue for you.

Example

let v = AtomicF32::new(5.0);
assert_eq!(v.compare_exchange(5.0, 10.0, Acquire, Relaxed), Ok(5.0));
assert_eq!(v.load(Relaxed), 10.0);

assert_eq!(v.compare_exchange(6.0, 12.0, SeqCst, Relaxed), Err(10.0));
assert_eq!(v.load(Relaxed), 10.0);

pub fn compare_exchange_weak(
    &self,
    current: f32,
    new: f32,
    success: Ordering,
    failure: Ordering
) -> Result<f32, f32>

Stores a value into the atomic integer if the current value is the same as the current value.

Unlike compare_exchange, this function is allowed to spuriously fail even when the comparison succeeds, which can result in more efficient code on some platforms. The return value is a result indicating whether the new value was written and containing the previous value.

compare_exchange_weak takes two Ordering arguments to describe the memory ordering of this operation. The first describes the required ordering if the operation succeeds while the second describes the required ordering when the operation fails. Using Acquire as success ordering makes the store part of this operation Relaxed, and using Release makes the successful load Relaxed. The failure ordering can only be SeqCst, Acquire or Relaxed and must be equivalent to or weaker than the success ordering.

Caveats

As the current parameter must be bitwise identical to the previous value, you should not get the current value using any sort of arithmetic (both because of rounding, and to avoid any situation where -0.0 and +0.0 would be compared). Additionally, on Wasm, in some cases NaN values have been known to cause problems for non-typical usage of this API. See AtomicF32::as_atomic_bits if performing the compare_exchange on the raw bits of this atomic float would solve an issue for you.

Example

Note that this sort of CaS loop should generally use fetch_update instead.

let v = AtomicF32::new(5.0);
let mut old = v.load(Relaxed);
loop {
    let new = old * 2.0;
    match v.compare_exchange_weak(old, new, SeqCst, Relaxed) {
        Ok(_) => break,
        Err(x) => old = x,
    }
}

pub fn fetch_update<F>(
    &self,
    set_order: Ordering,
    fetch_order: Ordering,
    update: F
) -> Result<f32, f32> where
    F: FnMut(f32) -> Option<f32>, 

Fetches the value, and applies a function to it that returns an optional new value. Returns a Result of Ok(previous_value) if the function returned Some(_), else Err(previous_value).

Note: This may call the function multiple times if the value has been changed from other threads in the meantime, as long as the function returns Some(_), but the function will have been applied only once to the stored value.

fetch_update takes two Ordering arguments to describe the memory ordering of this operation. The first describes the required ordering for when the operation finally succeeds while the second describes the required ordering for loads. These correspond to the success and failure orderings of compare_exchange respectively.

Using Acquire as success ordering makes the store part of this operation Relaxed, and using Release makes the final successful load Relaxed. The (failed) load ordering can only be SeqCst, Acquire or Relaxed and must be equivalent to or weaker than the success ordering.

Example

let x = AtomicF32::new(7.0);

assert_eq!(x.fetch_update(SeqCst, SeqCst, |_| None), Err(7.0));
assert_eq!(x.fetch_update(SeqCst, SeqCst, |x| Some(x + 1.0)), Ok(7.0));
assert_eq!(x.fetch_update(SeqCst, SeqCst, |x| Some(x + 1.0)), Ok(8.0));
assert_eq!(x.load(SeqCst), 9.0);

pub fn fetch_add(&self, val: f32, order: Ordering) -> f32

Adds to the current value, returning the previous value.

Because this returns the previous value, you may want to call it like: atom.fetch_add(x, order) + x

Examples

let x = AtomicF32::new(7.0);

assert_eq!(x.fetch_add(2.0, Relaxed), 7.0);
assert_eq!(x.fetch_add(1.0, SeqCst), 9.0);
assert_eq!(x.fetch_add(-100.0, AcqRel), 10.0);

pub fn fetch_sub(&self, val: f32, order: Ordering) -> f32

Subtract from the current value, returning the previous value.

Because this returns the previous value, you may want to call it like: atom.fetch_sub(x, order) - x

Note: This operation uses fetch_update under the hood, and is likely to be slower than the equivalent operation for atomic integers.

Examples

let x = AtomicF32::new(7.0);
assert_eq!(x.fetch_sub(2.0, Relaxed), 7.0);
assert_eq!(x.fetch_sub(-1.0, SeqCst), 5.0);
assert_eq!(x.fetch_sub(0.5, AcqRel), 6.0);

pub fn fetch_abs(&self, order: Ordering) -> f32

Produce the absolute value of the current value, returning the previous value.

Examples

let x = AtomicF32::new(-7.0);
assert_eq!(x.fetch_abs(Relaxed), -7.0);
assert_eq!(x.fetch_abs(SeqCst), 7.0);

pub fn fetch_neg(&self, order: Ordering) -> f32

Negates the current value, returning the previous value.

As a result of returning the previous value, you may want to invoke it like: -atom.fetch_neg(Relaxed).

Examples

let x = AtomicF32::new(-7.0);
assert_eq!(x.fetch_neg(Relaxed), -7.0);
assert_eq!(x.fetch_neg(SeqCst), 7.0);
assert_eq!(x.fetch_neg(AcqRel), -7.0);

pub fn fetch_min(&self, value: f32, order: Ordering) -> f32

Minimum with the current value.

Finds the minimum of the current value and the argument val, and sets the new value to the result.

Returns the previous value. Because of this, you may want to call it like: atom.fetch_min(x, order).min(x)

Note: This operation uses fetch_update under the hood, and is likely to be slower than the equivalent operation for atomic integers.

Examples

let foo = AtomicF32::new(23.0);
assert_eq!(foo.fetch_min(42.0, Ordering::Relaxed), 23.0);
assert_eq!(foo.load(Ordering::Relaxed), 23.0);
assert_eq!(foo.fetch_min(22.0, Ordering::Relaxed), 23.0);
assert_eq!(foo.load(Ordering::Relaxed), 22.0);

pub fn fetch_max(&self, value: f32, order: Ordering) -> f32

Maximum with the current value.

Finds the maximum of the current value and the argument val, and sets the new value to the result.

Returns the previous value. Because of this, you may want to call it like: atom.fetch_max(x, order).max(x)

Note: This operation uses fetch_update under the hood, and is likely to be slower than the equivalent operation for atomic integers.

Examples

let foo = AtomicF32::new(23.0);
assert_eq!(foo.fetch_max(22.0, Ordering::Relaxed), 23.0);
assert_eq!(foo.load(Ordering::Relaxed), 23.0);
assert_eq!(foo.fetch_max(42.0, Ordering::Relaxed), 23.0);
assert_eq!(foo.load(Ordering::Relaxed), 42.0);

pub fn as_atomic_bits(&self) -> &AtomicU32

Returns a reference to an atomic integer which can be used to access the atomic float’s underlying bits in a thread safe manner.

This is essentially a transmute::<&Self, &AtomicU32>(self), and is zero cost.

Motivation

This is exposed as an escape hatch because of the caveats around the AtomicF32 CaS-family APIs (compare_and_swap, compare_exchange, compare_exchange_weak, …) and the notion of bitwise identicality which they require being somewhat problematic for NaNs, especially on targets like Wasm (see rust-lang/rust#73328).

In general despite how bad this might sound, in practice we’re fairly safe: LLVM almost never optimizes through atomic operations, this library is written to try to avoid potential issues from most naive usage, and I’m optimistic the situation will clean itself up in the short-to-medium-term future.

However, if you need peace of mind, or find yourself in a case where you suspect you’re hitting this issue, you can access the underlying atomic value using this function.

Examples

let v = AtomicF32::new(22.5);
assert_eq!(v.as_atomic_bits().load(Ordering::Relaxed), 22.5f32.to_bits());

Trait Implementations

impl Debug for AtomicF32

Equivalent to <f32 as core::fmt::Debug>::fmt.

Example

let v = AtomicF32::new(40.0);
assert_eq!(format!("{:?}", v), format!("{:?}", 40.0f32));

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for AtomicF32

Return a zero-initialized atomic.

Example

let x = AtomicF32::default();
assert_eq!(x.load(Ordering::SeqCst), 0.0);

pub fn default() -> AtomicF32

Returns the “default value” for a type.

impl From<f32> for AtomicF32

Equivalent to AtomicF32::new.

Example

let v = AtomicF32::from(10.0);
assert_eq!(v.load(Ordering::SeqCst), 10.0);

pub fn from(f: f32) -> AtomicF32

Performs the conversion.

impl Send for AtomicF32

impl Sync for AtomicF32