std::sync::atomic - Rust
Description: API documentation for the Rust `atomic` mod in crate `std`.
Keywords: rust, rustlang, rust-lang, atomic

# Module std::sync::atomic 1.0.0 [−] [src]

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, including `AtomicBool`, `AtomicIsize`, and `AtomicUsize`. Atomic types present operations that, when used correctly, synchronize updates between threads.

Each method takes an `Ordering` which represents the strength of the memory barrier for that operation. These orderings are the same as LLVM atomic orderings. For more information see the nomicon.

Atomic variables are safe to share between threads (they implement `Sync`) but they do not themselves provide the mechanism for sharing and follow the threading model of rust. The most common way to share an atomic variable is to put it into an `Arc` (an atomically-reference-counted shared pointer).

Most atomic types may be stored in static variables, initialized using the provided static initializers like `ATOMIC_BOOL_INIT`. Atomic statics are often used for lazy global initialization.

# Examples

A simple spinlock:

    use std::sync::Arc;
    use std::sync::atomic::{AtomicUsize, Ordering};
    use std::thread;

    fn main() {
        let spinlock = Arc::new(AtomicUsize::new(1));

        let spinlock_clone = spinlock.clone();
        let thread = thread::spawn(move|| {
            spinlock_clone.store(0, Ordering::SeqCst);
        });

        // Wait for the other thread to release the lock
        while spinlock.load(Ordering::SeqCst) != 0 {}

        if let Err(panic) = thread.join() {
            println!("Thread had an error: {:?}", panic);
        }
    }Run

Keep a global count of live threads:

    use std::sync::atomic::{AtomicUsize, Ordering, ATOMIC_USIZE_INIT};

    static GLOBAL_THREAD_COUNT: AtomicUsize = ATOMIC_USIZE_INIT;

    let old_thread_count = GLOBAL_THREAD_COUNT.fetch_add(1, Ordering::SeqCst);
    println!("live threads: {}", old_thread_count + 1);Run

## Structs

AtomicBool | A boolean 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.
AtomicUsize | An integer type which can be safely shared between threads.
AtomicI8 | [ Experimental ] An integer type which can be safely shared between threads.
AtomicI16 | [ Experimental ] An integer type which can be safely shared between threads.
AtomicI32 | [ Experimental ] An integer type which can be safely shared between threads.
AtomicI64 | [ Experimental ] An integer type which can be safely shared between threads.
AtomicU8 | [ Experimental ] An integer type which can be safely shared between threads.
AtomicU16 | [ Experimental ] An integer type which can be safely shared between threads.
AtomicU32 | [ Experimental ] An integer type which can be safely shared between threads.
AtomicU64 | [ Experimental ] An integer type which can be safely shared between threads.

## Enums

Ordering | Atomic memory orderings

## Constants

ATOMIC_BOOL_INIT | An `AtomicBool` initialized to `false`.
ATOMIC_ISIZE_INIT | An atomic integer initialized to `0`.
ATOMIC_USIZE_INIT | An atomic integer initialized to `0`.
ATOMIC_I16_INIT | [ Experimental ] An atomic integer initialized to `0`.
ATOMIC_I32_INIT | [ Experimental ] An atomic integer initialized to `0`.
ATOMIC_I64_INIT | [ Experimental ] An atomic integer initialized to `0`.
ATOMIC_I8_INIT | [ Experimental ] An atomic integer initialized to `0`.
ATOMIC_U16_INIT | [ Experimental ] An atomic integer initialized to `0`.
ATOMIC_U32_INIT | [ Experimental ] An atomic integer initialized to `0`.
ATOMIC_U64_INIT | [ Experimental ] An atomic integer initialized to `0`.
ATOMIC_U8_INIT | [ Experimental ] An atomic integer initialized to `0`.

## Functions

compiler_fence | A compiler memory fence.
fence | An atomic fence.
hint_core_should_pause | [ Experimental ] Save power or switch hyperthreads in a busy-wait spin-loop.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)