portable-atomic 0.1.1

Portable atomic types.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# portable-atomic

[![crates.io](https://img.shields.io/crates/v/portable-atomic?style=flat-square&logo=rust)](https://crates.io/crates/portable-atomic)
[![docs.rs](https://img.shields.io/badge/docs.rs-portable--atomic-blue?style=flat-square)](https://docs.rs/portable-atomic)
[![license](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue?style=flat-square)](#license)
[![rustc](https://img.shields.io/badge/rustc-1.34+-blue?style=flat-square&logo=rust)](https://www.rust-lang.org)
[![build status](https://img.shields.io/github/workflow/status/taiki-e/portable-atomic/CI/main?style=flat-square&logo=github)](https://github.com/taiki-e/portable-atomic/actions)

Portable atomic types.

- 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 atomic load/store for targets where atomic is not available at all in the standard library. (riscv without A-extension, msp430, avr)
- (optional) Provide `Atomic{I,U}128`.
- (optional) Provide `AtomicF{32,64}`.
<!-- - (optional) Provide generic `Atomic<T>` type. -->
- (optional, [single-core only](#optional-cfg)) Provide atomic CAS for targets where atomic CAS is not available in the standard library. (thumbv6m, riscv without A-extension, msp430, avr)

## Optional features

- **`fallback`** *(enabled by default)*<br>
  Enable fallback implementations.

- **`i128`**<br>
  Provide `Atomic{I,U}128`.

  Note:
  - This implicitly enables the `fallback` feature.
  - Atomic operations are only available for Rust 1.59+ on x86_64 and nightly on aarch64, otherwise the fallback implementation is used.
  - On x86_64, when `cmpxchg16b` target feature is not enabled at compile time, this uses the fallback implementation. `cmpxchg16b` is enabled by default only on macOS.

  The above status is likely to change in the future:
  - When `Atomic{I,U}128` is stabilized in the standard library.
  - When 128-bit atomic operations are supported in other architectures. ([riscv](https://lists.riscv.org/g/tech/topic/requirements_for_128_bit/76126473?p=))

  If you need support for dynamic CPU feature detection, use the `i128-dynamic` feature.

- **`i128-dynamic`**<br>
  Similar to the `i128` feature, but tries to use `cmpxchg16b` in more cases based on dynamic CPU feature detection.

  Note:
  - Dynamic detection is only enabled in nightly, otherwise it works the same as the `i128` feature.
  - When `cmpxchg16b` target feature is enabled at compile time, this works exactly the same as the `i128` feature.
  - If both `i128` and `i128-dynamic` features are used in the dependency graph, `i128-dynamic` takes precedence.
  - This is compatible with no-std (as with all features except std).

- **`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.

<!-- TODO
- **`generic`**<br>
  Provides generic `Atomic<T>` type.
-->

- **`std`**<br>
  Use `std`.

- **`serde`**<br>
  Implement `serde::{Serialize,Deserialize}` for atomic types.

## 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.

## 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.