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 [#1] for other primitives being considered for addition to this crate.
15
16## Optional features
17
18- **`std`**<br>
19  Use `std`.
20
21  Note:
22  - This implicitly enables the `alloc` feature.
23
24- **`alloc`**<br>
25  Use `alloc`.
26
27  Note:
28  - The MSRV when this feature is enabled and the `std` feature is *not* enabled is Rust 1.36 that `alloc` crate stabilized.
29
30<!-- TODO: https://github.com/taiki-e/portable-atomic/issues/1
31- **`generic`**<br>
32  Provides generic `Atomic<T>` type.
33-->
34
35[portable-atomic]: https://github.com/taiki-e/portable-atomic
36[#1]: https://github.com/taiki-e/portable-atomic/issues/1
37
38## Optional cfg
39
40One of the ways to enable cfg is to set [rustflags in the cargo config](https://doc.rust-lang.org/cargo/reference/config.html#targettriplerustflags):
41
42```toml
43# .cargo/config.toml
44[target.<target>]
45rustflags = ["--cfg", "portable_atomic_unstable_coerce_unsized"]
46```
47
48Or set environment variable:
49
50```sh
51RUSTFLAGS="--cfg portable_atomic_unstable_coerce_unsized" cargo ...
52```
53
54- <a name="optional-cfg-unstable-coerce-unsized"></a>**`--cfg portable_atomic_unstable_coerce_unsized`**<br>
55  Support coercing of `Arc<T>` to `Arc<U>` as in `std::sync::Arc`.
56
57  <!-- TODO: add coercing of `Weak<T>` to `Weak<U>` as well, with testing & documentation updates -->
58
59  This cfg requires Rust nightly because this coercing requires [unstable `CoerceUnsized` trait](https://doc.rust-lang.org/nightly/core/ops/trait.CoerceUnsized.html).
60
61  See [this issue comment](https://github.com/taiki-e/portable-atomic/issues/143#issuecomment-1866488569) for another known workaround.
62
63  **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.
64
65<!-- tidy:sync-markdown-to-rustdoc:end -->
66*/
67
68#![no_std]
69#![doc(test(
70    no_crate_inject,
71    attr(
72        deny(warnings, rust_2018_idioms, single_use_lifetimes),
73        allow(dead_code, unused_variables)
74    )
75))]
76#![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
77#![cfg_attr(portable_atomic_no_unsafe_op_in_unsafe_fn, allow(unused_unsafe))]
78#![warn(
79    // Lints that may help when writing public library.
80    missing_debug_implementations,
81    missing_docs,
82    clippy::alloc_instead_of_core,
83    clippy::exhaustive_enums,
84    clippy::exhaustive_structs,
85    clippy::impl_trait_in_params,
86    // clippy::missing_inline_in_public_items,
87    clippy::std_instead_of_alloc,
88    clippy::std_instead_of_core,
89)]
90#![cfg_attr(portable_atomic_no_strict_provenance, allow(unstable_name_collisions))]
91#![allow(clippy::inline_always)]
92// docs.rs only (cfg is enabled by docs.rs, not build script)
93#![cfg_attr(docsrs, feature(doc_cfg))]
94#![cfg_attr(docsrs, doc(auto_cfg = false))]
95// Enable custom unsized coercions if the user explicitly opts-in to unstable cfg
96#![cfg_attr(portable_atomic_unstable_coerce_unsized, feature(coerce_unsized, unsize))]
97
98#[cfg(all(feature = "alloc", not(portable_atomic_no_alloc)))]
99extern crate alloc;
100#[cfg(feature = "std")]
101extern crate std;
102#[cfg(all(feature = "std", portable_atomic_no_alloc))]
103extern crate std as alloc;
104
105#[macro_use]
106mod utils;
107
108#[cfg(any(all(feature = "alloc", not(portable_atomic_no_alloc)), feature = "std"))]
109#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
110mod arc;
111#[cfg(any(all(feature = "alloc", not(portable_atomic_no_alloc)), feature = "std"))]
112pub use self::arc::{Arc, Weak};
113
114#[cfg(not(portable_atomic_no_futures_api))]
115#[cfg(any(all(feature = "alloc", not(portable_atomic_no_alloc)), feature = "std"))]
116#[cfg_attr(docsrs, doc(cfg(any(feature = "alloc", feature = "std"))))]
117pub mod task;
portable_atomic_util/lib.rs

portable_atomic_util/
lib.rs
