atomic-int 0.1.5

Atomics for additional integers, like C/FFI 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

atomic-int
==========

atomic-int provides atomics for additional integers, such as C/FFI types
like [`c_int`].

For integer types that are aliases of primitive integers that have built-in
Rust atomics, this crate simply re-exports those atomics. Otherwise, this
crate provides a spinlock-based fallback implementation with a compatible
API.

This crate also provides types that directly correspond with Rust’s
standard atomics, like [`AtomicU64`], with the difference that the fallback
implementation will similarly be used for any such atomics that are not
supported on a given platform. Thus, all atomics provided by this crate are
available on all platforms[^1] in some form—either the built-in or fallback
implementation.

[^1]: As long as the platform supports [`AtomicBool`], and compare-and-swap
      operations on [`AtomicBool`], which are required for the fallback
      implementation.

Crate features
--------------

Types that directly correspond with Rust’s standard atomics like
[`AtomicU64`] are available with the feature `primitives` (enabled by
default). This includes [`AtomicPtr`], even though it isn’t exactly an
integer.

Atomic C integer types like [`AtomicCInt`] and [`AtomicCUlong`] are
available with the feature `c` (enabled by default). For more granularity,
a separate feature exists for each C integer (e.g., `c_int` and `c_ulong`).

The spinlock-based fallback implementation can cause deadlocks with signal
handlers. To avoid this, enable the feature `signal`, which blocks incoming
signals while the lock is held. This feature is Unix-specific; on
non-Unix-like operating systems it is a no-op.

atomic-int can optionally depend on [`libc`]. If this dependency is
enabled, atomic-int will use the C integer types from [`libc`] instead of
[`core::ffi`]. This should not make a noticeable difference, but it can
decrease the minimum required Rust version, as C integer types were added
to [`core::ffi`] only in version 1.64. The feature `signal` always enables
`libc`.

For development purposes, the feature `force-fallback` is provided. This
forces the fallback implementation to be used for all atomics, which can
help you ensure your program doesn’t rely on functionality only provided by
the native atomic types. It should not normally be enabled outside of
testing.

Use without `std`
-----------------

This crate is `no_std` when `libc` is not enabled.

[`libc`]: https://docs.rs/libc/0.2
[`c_int`]: https://doc.rust-lang.org/stable/core/ffi/type.c_int.html
[`AtomicU64`]: https://docs.rs/atomic-int/0.1/atomic_int/type.AtomicU64.html
[`AtomicPtr`]: https://docs.rs/atomic-int/0.1/atomic_int/type.AtomicPtr.html
[`AtomicCInt`]: https://docs.rs/atomic-int/0.1/atomic_int/type.AtomicCInt.html
[`AtomicCUlong`]: https://docs.rs/atomic-int/0.1/atomic_int/type.AtomicCUlong.html
[`core::ffi`]: https://doc.rust-lang.org/stable/core/ffi/
[`AtomicBool`]: https://doc.rust-lang.org/stable/core/sync/atomic/struct.AtomicBool.html