portable_atomic_util/
lib.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3/*!
4<!-- Note: Document from sync-markdown-to-rustdoc:start through sync-markdown-to-rustdoc:end
5     is synchronized from README.md. Any changes to that range are not preserved. -->
6<!-- tidy:sync-markdown-to-rustdoc:start -->
7
8Synchronization primitives built with [portable-atomic].
9
10- Provide `Arc`. (optional, requires the `std` or `alloc` feature)
11- Provide `task::Wake`. (optional, requires the `std` or `alloc` feature)
12<!-- - Provide generic `Atomic<T>` type. (optional, requires the `generic` feature) -->
13
14See [portable-atomic#1] for other primitives being considered for addition to this crate.
15
16This crate was originally [part of the portable-atomic repository](https://github.com/taiki-e/portable-atomic/tree/cbbee0c0d202a5944f7d66aaafaac6ed76e6f599/portable-atomic-util) and was extracted into its own repository.
17
18## Optional features
19
20- **`std`**<br>
21  Use `std`.
22
23  Note:
24  - This implicitly enables the `alloc` feature.
25
26- **`alloc`**<br>
27  Use `alloc`.
28
29  Note:
30  - The MSRV when this feature is enabled and the `std` feature is *not* enabled is Rust 1.36 that `alloc` crate stabilized.
31
32- **`serde`**<br>
33  Implement `serde::{Serialize, Deserialize}` for `Arc`.
34
35  Note:
36  - The MSRV when this feature is enabled is the one coming from serde, as of now it's Rust 1.56
37
38<!-- TODO: https://github.com/taiki-e/portable-atomic/issues/1
39- **`generic`**<br>
40  Provides generic `Atomic<T>` type.
41-->
42
43[portable-atomic]: https://github.com/taiki-e/portable-atomic
44[portable-atomic#1]: https://github.com/taiki-e/portable-atomic/issues/1
45
46## Optional cfg
47
48One of the ways to enable cfg is to set [rustflags in the cargo config](https://doc.rust-lang.org/cargo/reference/config.html#targettriplerustflags):
49
50```toml
51# .cargo/config.toml
52[target.<target>]
53rustflags = ["--cfg", "portable_atomic_unstable_coerce_unsized"]
54```
55
56Or set environment variable:
57
58```sh
59RUSTFLAGS="--cfg portable_atomic_unstable_coerce_unsized" cargo ...
60```
61
62- <a name="optional-cfg-unstable-coerce-unsized"></a>**`--cfg portable_atomic_unstable_coerce_unsized`**<br>
63  Support coercing of `Arc<T>` to `Arc<U>` as in `std::sync::Arc`.
64
65  <!-- TODO: add coercing of `Weak<T>` to `Weak<U>` as well, with testing & documentation updates -->
66
67  This cfg requires Rust nightly because this coercing requires [unstable `CoerceUnsized` trait](https://doc.rust-lang.org/nightly/core/ops/trait.CoerceUnsized.html).
68
69  See [this issue comment](https://github.com/taiki-e/portable-atomic/issues/143#issuecomment-1866488569) for another known workaround.
70
71  **Note:** This cfg is unstable and outside of the normal semver guarantees and minor or patch versions of portable-atomic-util may make breaking changes to them at any time.
72
73## Related Projects
74
75- [portable-atomic]: Portable atomic types including support for 128-bit atomics, atomic float, etc.
76- [atomic-maybe-uninit]: Atomic operations on potentially uninitialized integers.
77- [atomic-memcpy]: Byte-wise atomic memcpy.
78
79[atomic-maybe-uninit]: https://github.com/taiki-e/atomic-maybe-uninit
80[atomic-memcpy]: https://github.com/taiki-e/atomic-memcpy
81
82<!-- tidy:sync-markdown-to-rustdoc:end -->
83*/
84
85#![no_std]
86#![doc(test(
87    no_crate_inject,
88    attr(allow(
89        dead_code,
90        unused_variables,
91        clippy::undocumented_unsafe_blocks,
92        clippy::unused_trait_names,
93    ))
94))]
95#![cfg_attr(not(portable_atomic_no_unsafe_op_in_unsafe_fn), warn(unsafe_op_in_unsafe_fn))] // unsafe_op_in_unsafe_fn requires Rust 1.52
96#![cfg_attr(portable_atomic_no_unsafe_op_in_unsafe_fn, allow(unused_unsafe))]
97#![warn(
98    // Lints that may help when writing public library.
99    missing_debug_implementations,
100    missing_docs,
101    clippy::alloc_instead_of_core,
102    clippy::exhaustive_enums,
103    clippy::exhaustive_structs,
104    clippy::impl_trait_in_params,
105    clippy::std_instead_of_alloc,
106    clippy::std_instead_of_core,
107    // clippy::missing_inline_in_public_items,
108)]
109#![cfg_attr(portable_atomic_no_strict_provenance, allow(unstable_name_collisions))]
110#![allow(clippy::inline_always)]
111// docs.rs only (cfg is enabled by docs.rs, not build script)
112#![cfg_attr(docsrs, feature(doc_cfg))]
113#![cfg_attr(docsrs, doc(auto_cfg = false))]
114// Enable custom unsized coercions if the user explicitly opts-in to unstable cfg
115#![cfg_attr(portable_atomic_unstable_coerce_unsized, feature(coerce_unsized, unsize))]
116
117#[cfg(all(feature = "alloc", not(portable_atomic_no_alloc)))]
118extern crate alloc;
119#[cfg(feature = "std")]
120extern crate std;
121#[cfg(all(feature = "std", portable_atomic_no_alloc))]
122extern crate std as alloc;
123
124#[macro_use]
125mod utils;
126
127#[cfg(any(all(feature = "alloc", not(portable_atomic_no_alloc)), feature = "std"))]
128mod arc;
129#[cfg(any(all(feature = "alloc", not(portable_atomic_no_alloc)), feature = "std"))]
130#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
131pub use self::arc::{Arc, Weak};
132
133#[cfg(not(portable_atomic_no_futures_api))]
134#[cfg(any(all(feature = "alloc", not(portable_atomic_no_alloc)), feature = "std"))]
135#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
136pub mod task;
portable_atomic_util/lib.rs

portable_atomic_util/
lib.rs
