no-std portable-atomic

Portable atomic types including support for 128-bit atomics, atomic float, etc

25 releases (2 stable)

1.0.1 Jan 21, 2023
0.3.19 Dec 25, 2022
0.3.15 Sep 9, 2022
0.3.7 Jul 31, 2022
0.3.0 Mar 25, 2022

#136 in Concurrency

Download history 98318/week @ 2022-11-30 89012/week @ 2022-12-07 91198/week @ 2022-12-14 55861/week @ 2022-12-21 52809/week @ 2022-12-28 81577/week @ 2023-01-04 90959/week @ 2023-01-11 100140/week @ 2023-01-18 108187/week @ 2023-01-25 110412/week @ 2023-02-01 115981/week @ 2023-02-08 118199/week @ 2023-02-15 118407/week @ 2023-02-22 112392/week @ 2023-03-01 133204/week @ 2023-03-08 113102/week @ 2023-03-15

498,642 downloads per month
Used in 635 crates (54 directly)

Apache-2.0 OR MIT

12K SLoC


crates.io docs.rs license rustc build status build status

Portable atomic types including support for 128-bit atomics, atomic float, etc.

  • Provide all atomic integer types (Atomic{I,U}{8,16,32,64}) for all targets that can use atomic CAS. (i.e., all targets that can use std, and most no-std targets)
  • Provide AtomicI128 and AtomicU128.
  • Provide AtomicF32 and AtomicF64. (optional, requires the float feature)
  • Provide atomic load/store for targets where atomic is not available at all in the standard library. (RISC-V without A-extension, MSP430, AVR)
  • Provide atomic CAS for targets where atomic CAS is not available in the standard library. (thumbv6m, pre-v6 ARM, RISC-V without A-extension, MSP430, AVR, etc.) (always enabled for MSP430 and AVR, optional otherwise)
  • Provide stable equivalents of the standard library's atomic types' unstable APIs, such as AtomicPtr::fetch_*, AtomicBool::fetch_not.
  • Make features that require newer compilers, such as fetch_max, fetch_min, fetch_update, and stronger CAS failure ordering available on Rust 1.34+.
  • Provide workaround for bugs in the standard library's atomic-related APIs, such as rust-lang/rust#100650, fence/compiler_fence on MSP430 that cause LLVM error, etc.


Add this to your Cargo.toml:

portable-atomic = "1"

The default features are mainly for users who use atomics larger than the pointer width. If you don't need them, disabling the default features may reduce code size and compile time slightly.

portable-atomic = { version = "1", default-features = false }

Compiler support: requires rustc 1.34+

128-bit atomics support

Native 128-bit atomic operations are available on x86_64 (Rust 1.59+), aarch64 (Rust 1.59+), powerpc64 (le or pwr8+, nightly only), and s390x (nightly only), otherwise the fallback implementation is used.

On x86_64, even if cmpxchg16b is not available at compile time (note: cmpxchg16b target feature is enabled by default only on macOS), run-time detection checks whether cmpxchg16b is available. If cmpxchg16b is not available at either compile-time or run-time detection, the fallback implementation is used. See also portable_atomic_no_outline_atomics cfg.

They are usually implemented using inline assembly, and when using Miri or ThreadSanitizer that do not support inline assembly, core intrinsics are used instead of inline assembly if possible.

See also the atomic128 module's readme.

Optional features

  • fallback *(enabled by default)*
    Enable fallback implementations.

    Disabling this allows only atomic types for which the platform natively supports atomic operations.

  • float
    Provide AtomicF{32,64}. Note that most of fetch_* operations of atomic floats are implemented using CAS loops, which can be slower than equivalent operations of atomic integers.

  • std
    Use std.

  • serde
    Implement serde::{Serialize,Deserialize} for atomic types.


    • The MSRV when this feature is enabled depends on the MSRV of serde.
  • critical-section
    When this feature is enabled, this crate uses critical-section to provide atomic CAS for targets where it is not natively available. When enabling it, you should provide a suitable critical section implementation for the current target, see the critical-section documentation for details on how to do so.

    critical-section support is useful to get atomic CAS when --cfg portable_atomic_unsafe_assume_single_core can't be used, such as multi-core targets, unprivileged code running under some RTOS, or environments where disabling interrupts needs extra care due to e.g. real-time requirements.

    Note that with the critical-section feature, critical sections are taken for all atomic operations, while with --cfg portable_atomic_unsafe_assume_single_core some operations don't require disabling interrupts (loads and stores, but additionally on MSP430 add, sub, and, or, xor, not). Therefore, for better performance, if all the critical-section implementation for your target does is disable interrupts, prefer using --cfg portable_atomic_unsafe_assume_single_core instead.


    • The MSRV when this feature is enabled depends on the MSRV of critical-section.

    • It is usually not recommended to always enable this feature in dependencies of the library.

      Enabling this feature will prevent the end user from having the chance to take advantage of other (potentially) efficient implementations (Implementations provided by --cfg portable_atomic_unsafe_assume_single_core, default implementations on MSP430 and AVR, implementation proposed in #60, etc. Other systems may also be supported in the future).

      The recommended approach for libraries is to leave it up to the end user whether or not to enable this feature. (However, it may make sense to enable this feature by default for libraries specific to a platform where other implementations are known not to work.)

Optional cfg

  • --cfg portable_atomic_unsafe_assume_single_core
    Assume that the target is single-core. When this cfg is enabled, this crate provides atomic CAS for targets where atomic CAS is not available in the standard library by disabling interrupts.

    This cfg is unsafe, and note the following safety requirements:

    • Enabling this cfg for multi-core systems is always unsound.

    • This uses privileged instructions to disable interrupts, so it usually doesn't work on unprivileged mode. Enabling this cfg in an environment where privileged instructions are not available, or if the instructions used are not sufficient to disable interrupts in the system, it is also usually considered unsound, although the details are system-dependent.

      The following are known cases:

      • On pre-v6 ARM, this disables only IRQs by default. For many systems (e.g., GBA) this is enough. If the system need to disable both IRQs and FIQs, you need to pass the --cfg portable_atomic_disable_fiq together.
      • On RISC-V without A-extension, this generates code for machine-mode (M-mode) by default. If you pass the --cfg portable_atomic_s_mode together, this generates code for supervisor-mode (S-mode). In particular, qemu-system-riscv* uses OpenSBI as the default firmware.

      See also the interrupt module's readme.

    Consider using the critical-section feature for systems that cannot use this cfg.

    This is intentionally not an optional feature. (If this is an optional feature, dependencies can implicitly enable the feature, resulting in the use of unsound code without the end-user being aware of it.)

    ARMv6-M (thumbv6m), pre-v6 ARM (e.g., thumbv4t, thumbv5te), RISC-V without A-extension are currently supported.

    Since all MSP430 and AVR are single-core, we always provide atomic CAS for them without this cfg.

    Enabling this cfg for targets that have atomic CAS will result in a compile error.

    Feel free to submit an issue if your target is not supported yet.

  • --cfg portable_atomic_no_outline_atomics
    Disable dynamic dispatching by run-time CPU feature detection.

    If dynamic dispatching by run-time CPU feature detection is enabled, it allows maintaining support for older CPUs while using features that are not supported on older CPUs, such as CMPXCHG16B (x86_64) and FEAT_LSE (aarch64).


    • Dynamic detection is currently only enabled in Rust 1.61+ for aarch64, in 1.59+ (AVX) or nightly (CMPXCHG16B) for x86_64, and in nightly for other platforms, otherwise it works the same as when this cfg is set.
    • If the required target features are enabled at compile-time, the atomic operations are inlined.
    • This is compatible with no-std (as with all features except std).
    • Some aarch64 targets enable LLVM's outline-atomics target feature by default, so if you set this cfg, you may want to disable that as well.

    See also the atomic128 module's readme.


Licensed under either of Apache License, Version 2.0 or MIT license at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.