# portable-atomic
[](https://crates.io/crates/portable-atomic)
[](https://docs.rs/portable-atomic)
[](#license)
[](https://www.rust-lang.org)
[](https://github.com/taiki-e/portable-atomic/actions)
[](https://cirrus-ci.com/github/taiki-e/portable-atomic)
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)
- Provide atomic load/store for targets where atomic is not available at all in the standard library. (riscv without A-extension, msp430, avr)
- Provide atomic CAS for targets where atomic CAS is not available in the standard library. (thumbv6m, riscv without A-extension, msp430, avr) (optional, [single-core only](#optional-cfg))
## 128-bit atomics support (AtomicI128,AtomicU128)
Native 128-bit atomic operations are only available for x86_64 and aarch64 at Rust 1.59+, otherwise the fallback implementation is used.
On x86_64, when the `outline-atomics` optional feature is not enabled and `cmpxchg16b` target feature is not enabled at compile-time, this uses the fallback implementation. `cmpxchg16b` is enabled by default only on macOS.
## Optional features
- **`fallback`** *(enabled by default)*<br>
Enable fallback implementations.
Disabling this allows only atomic types for which the platform natively supports atomic operations.
- **`outline-atomics`**<br>
Enable run-time CPU feature detection.
This allows maintaining support for older CPUs while using features that are not supported on older CPUs, such as cmpxchg16b (x86_64) and LSE (aarch64).
Note:
- Dynamic detection is currently only enabled in Rust 1.61+ for aarch64 and in nightly for others, otherwise it works the same as the default.
- 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` and `parking_lot`).
- **`float`**<br>
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`**<br>
Use `std`.
- **`serde`**<br>
Implement `serde::{Serialize,Deserialize}` for atomic types.
Note:
- The MSRV when this feature enables depends on the MSRV of [serde].
- **`parking_lot`**<br>
Use [parking_lot] in global locks of fallback implementation.
Note:
- This is not compatible with no-std.
- The MSRV when this feature enables depends on the MSRV of [parking_lot].
## Optional cfg
- **`--cfg portable_atomic_unsafe_assume_single_core`**<br>
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.
Note: This cfg is `unsafe`, and enabling this cfg for multi-core systems is **unsound**.
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.)
## Related Projects
- [atomic-maybe-uninit]: Atomic operations on potentially uninitialized integers.
- [atomic-memcpy]: Byte-wise atomic memcpy.
[atomic-memcpy]: https://github.com/taiki-e/atomic-memcpy
[atomic-maybe-uninit]: https://github.com/taiki-e/atomic-maybe-uninit
[parking_lot]: https://github.com/Amanieu/parking_lot
[serde]: https://github.com/serde-rs/serde
## License
Licensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or
[MIT license](LICENSE-MIT) 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.