Module shuttle::sync::atomic

source ·
Expand description

Atomic types

Atomic types provide primitive shared-memory communication between threads, and are the building blocks of other concurrent types.

This module defines atomic versions of a select number of primitive types, the same as std::sync::atomic in the standard library. See that module’s documentation for more details.

§Warning about relaxed behaviors

Shuttle does not faithfully model behaviors of relaxed atomic orderings (those other than SeqCst). Code that uses these orderings may contain bugs that Shuttle is unable to find if the bug requires the relaxed behavior to occur. Shuttle models all atomic operations as if they were using SeqCst ordering.

For example, consider this test that uses a flag variable to indicate that data is present in a separate data variable:

let flag = Arc::new(AtomicBool::new(false));
let data = Arc::new(AtomicU64::new(0));

{
    let flag = Arc::clone(&flag);
    let data = Arc::clone(&data);
    thread::spawn(move|| {
        data.store(42, Ordering::Relaxed);
        flag.store(true, Ordering::Relaxed);
    });
}

if flag.load(Ordering::Relaxed) {
    assert_eq!(data.load(Ordering::Relaxed), 42);
}

This code is incorrect because of the relaxed orderings used for the loads and stores. Some architectures will allow an execution where flag is true but the assertion is false. However, Shuttle treats all atomic operations as SeqCst, and this test would be correct if we used SeqCst for all atomic operations, so Shuttle cannot find this bug.

If you are writing code that relies on relaxed atomic operations and need to check its correctness, the Loom crate provides support for reasoning about Acquire and Release orderings and partial support for Relaxed orderings.

To disable the warning printed about this issue, set the SHUTTLE_SILENCE_WARNINGS environment variable to any value, or set the silence_warnings field of Config to true.

Structs§

  • AtomicBool
    A boolean type which can be safely shared between threads.
  • AtomicI8
    An integer type which can be safely shared between threads.
  • AtomicI16
    An integer type which can be safely shared between threads.
  • AtomicI32
    An integer type which can be safely shared between threads.
  • AtomicI64
    An integer type which can be safely shared between threads.
  • AtomicIsize
    An integer type which can be safely shared between threads.
  • AtomicPtr
    A raw pointer type which can be safely shared between threads.
  • AtomicU8
    An integer type which can be safely shared between threads.
  • AtomicU16
    An integer type which can be safely shared between threads.
  • AtomicU32
    An integer type which can be safely shared between threads.
  • AtomicU64
    An integer type which can be safely shared between threads.
  • AtomicUsize
    An integer type which can be safely shared between threads.

Enums§

Functions§