atomic-bitflags 0.2.0

Atomic storage for bitflags flag sets
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
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# atomic-bitflags

Atomic storage for [bitflags](https://crates.io/crates/bitflags) flag sets.

`AtomicFlags<F>` stores the bits of a `bitflags` type in a standard library
atomic integer. Reads and writes are lock-free, and every operation takes an
`Ordering` exactly like `AtomicU32` or `AtomicU8`.

## Install

```toml
[dependencies]
atomic-bitflags = "0.1"
bitflags = "2"
```

## Use case

Runtime configuration that several threads read and a few threads update:
feature switches, log levels, or service modes. It is also a replacement for a
mutex around a flag set when you only need atomic reads, writes, and
set/clear/toggle operations.

```rust
use atomic_bitflags::AtomicFlags;
use bitflags::bitflags;
use std::sync::Arc;
use std::sync::atomic::Ordering;

bitflags! {
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    struct Features: u8 {
        const CACHE = 1 << 0;
        const TRACE = 1 << 1;
        const STRICT = 1 << 2;
    }
}

fn main() {
    let features = Arc::new(AtomicFlags::new(Features::CACHE));

    // Enable tracing from another thread.
    let remote = Arc::clone(&features);
    std::thread::spawn(move || {
        remote.set(Features::TRACE, Ordering::Release);
    })
    .join()
    .unwrap();

    let current = features.load(Ordering::Acquire);
    assert!(current.contains(Features::CACHE | Features::TRACE));

    // `take` claims flags atomically: only one caller can claim STRICT.
    features.set(Features::STRICT, Ordering::SeqCst);
    assert_eq!(features.take(Features::STRICT, Ordering::SeqCst), Features::STRICT);
    assert!(features.take(Features::STRICT, Ordering::SeqCst).is_empty());
}
```

Operations on a shared instance take `&self`, so wrap the value in `Arc` to
share it. `AtomicFlags` is `Send + Sync`.

## API

| Method | Operation | Returns |
| --- | --- | --- |
| `new(flags)` | initialize | the new `AtomicFlags` |
| `from_storage(atomic)` | const initialize from a pre-built atomic | the new `AtomicFlags` |
| `load(ordering)` | atomic load | current flags |
| `store(flags, ordering)` | atomic store | nothing |
| `swap(flags, ordering)` | atomic swap | previous flags |
| `compare_exchange(current, new, success, failure)` | compare and swap | `Ok(previous)` or `Err(actual)` |
| `compare_exchange_weak(current, new, success, failure)` | same, may fail spuriously | `Ok(previous)` or `Err(actual)` |
| `set(flags, ordering)` | atomic OR | previous flags |
| `unset(flags, ordering)` | atomic AND NOT | previous flags |
| `clear(ordering)` | store empty | nothing |
| `take(flags, ordering)` | atomic AND NOT | requested flags that were set |
| `peek(flags, ordering)` | atomic load | requested flags that are set |
| `fetch_and(flags, ordering)` | atomic AND | previous flags |
| `fetch_or(flags, ordering)` | atomic OR | previous flags |
| `fetch_xor(flags, ordering)` | atomic XOR | previous flags |
| `toggle(flags, ordering)` | alias for `fetch_xor` | previous flags |
| `fetch_nand(flags, ordering)` | atomic NAND | previous flags |
| `try_update(set_order, fetch_order, f)` | apply `f` until it succeeds | `Ok(previous)` or `Err(current)` |
| `into_inner()` | consume | final flags |

`set` and `unset` are convenience wrappers around `fetch_or` and `fetch_and`.
The bitwise `fetch_*` methods return the full previous value; `try_update`
returns `Ok(previous)` on success, or `Err(current)` if the closure returns
`None`.

`compare_exchange` and `compare_exchange_weak` follow the standard atomics: on
failure they return the actual current value, and the failure ordering may not
be stronger than the success ordering.

`take` and `peek` return only the requested flags. `take` claims them with a
single atomic operation; `peek` is a plain load, so another thread may change
the value immediately after.

`fetch_nand` keeps the standard atomic semantics: the new value is
`!(current & flags)`, so bits outside `flags` are set as well.

### Static initialization

`from_storage` is const, so a flag set can live in a `static`:

```rust
use std::sync::atomic::AtomicU8;

static FEATURES: AtomicFlags<Features> =
    AtomicFlags::from_storage(AtomicU8::new(Features::CACHE.bits()));
```

The atomic type must match the bits type of the flag set (`u8` uses `AtomicU8`,
`u64` uses `AtomicU64`, and so on).

## Limits

- `u128` and `i128` are not supported because Rust has no 128-bit atomic
  integer.
- 64-bit flag sets need a target with 64-bit atomics, like any `AtomicU64`.
- Unknown bits are preserved on load (`from_bits_retain`), not truncated.
- No ordering is chosen for you; pick one with the same rules as the standard
  library atomics.

## License

MIT OR Apache-2.0.