Document the conditional existence of alloc::sync and alloc::task.
#98218
Conversation
The wording is copied from `std::sync::atomic::AtomicPtr`, with additional advice on how to `#[cfg]` for it.
|
Hey! It looks like you've submitted a new PR for the library teams! If this PR contains changes to any Examples of
|
rustbot
added
the
T-libs
|
(rust-highfive has picked a reviewer for you, use r? to override) |
rust-highfive
added
the
S-waiting-on-review
|
@rustbot label +A-docs |
rustbot
added
the
A-docs
|
The (unstable) |
| //! | ||
| //! **Note**: This module is only available on platforms that support atomic | ||
| //! loads and stores of pointers. This may be detected at compile time using | ||
| //! `#[cfg(target_has_atomic = "ptr")]`. |
There was a problem hiding this comment.
Hm, this might be true today, but in the future I could imagine that we'd have some parts of this module available even without atomics of pointer width.
It's already a bit weird that alloc::sync is not a superset of core::sync, it seems; that seems unusual.
There was a problem hiding this comment.
Hm, this might be true today, but in the future I could imagine that we'd have some parts of this module available even without atomics of pointer width.
The documentation could then be revised at the same time the cfg is removed.
It's already a bit weird that alloc::sync is not a superset of core::sync, it seems; that seems unusual.
That sounds like something worth fixing for consistency, but this change is forward-compatible with that — the note on the modules would just be removed, and the note on Arc kept. (alloc::task is in the same situation — and so technically the Wake trait should have a similar note.)
|
Going to reassign to @joshtriplett for T-libs-api review, since this is sort of a new documentation element. (And for thoughts on the re-export of core::sync::atomic from alloc::sync). |
JohnCSimon
added
S-waiting-on-review
|
The comments seem like a reasonable addition, given the current state. I also agree that these modules should be supersets of the modules in core, and when we go to change that (which probably needs an FCP), we can also change the documentation at that time. @bors r+ rollup |
bors
added
S-waiting-on-bors
Document the conditional existence of `alloc::sync` and `alloc::task`. `alloc` declares ```rust #[cfg(target_has_atomic = "ptr")] pub mod sync; ``` but there is no public documentation of this condition. This PR fixes that, so that users of `alloc` can understand how to make their code compile everywhere `alloc` does, if they are writing a library with impls for `Arc`. The wording is copied from `std::sync::atomic::AtomicPtr`, with additional advice on how to `#[cfg]` for it. I feel quite uncertain about whether the paragraph I added to `Arc`'s documentation should actually be there, as it is a distraction for anyone using `std`. On the other hand, maybe more reminders that no_std exists would benefit the ecosystem. Note: `target_has_atomic` is [stabilized](rust-lang#32976) but [not yet documented in the reference](rust-lang/reference#1171).
Document the conditional existence of `alloc::sync` and `alloc::task`. `alloc` declares ```rust #[cfg(target_has_atomic = "ptr")] pub mod sync; ``` but there is no public documentation of this condition. This PR fixes that, so that users of `alloc` can understand how to make their code compile everywhere `alloc` does, if they are writing a library with impls for `Arc`. The wording is copied from `std::sync::atomic::AtomicPtr`, with additional advice on how to `#[cfg]` for it. I feel quite uncertain about whether the paragraph I added to `Arc`'s documentation should actually be there, as it is a distraction for anyone using `std`. On the other hand, maybe more reminders that no_std exists would benefit the ecosystem. Note: `target_has_atomic` is [stabilized](rust-lang#32976) but [not yet documented in the reference](rust-lang/reference#1171).
…iaskrgr Rollup of 7 pull requests Successful merges: - rust-lang#98218 (Document the conditional existence of `alloc::sync` and `alloc::task`.) - rust-lang#99216 (docs: be less harsh in wording for Vec::from_raw_parts) - rust-lang#99460 (docs: Improve AsRef / AsMut docs on blanket impls) - rust-lang#100470 (Tweak `FpCategory` example order.) - rust-lang#101040 (Fix `#[derive(Default)]` on a generic `#[default]` enum adding unnecessary `Default` bounds) - rust-lang#101308 (introduce `{char, u8}::is_ascii_octdigit`) - rust-lang#102486 (Add diagnostic struct for const eval error in `rustc_middle`) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
allocdeclaresbut there is no public documentation of this condition. This PR fixes that, so that users of
alloccan understand how to make their code compile everywhereallocdoes, if they are writing a library with impls forArc.The wording is copied from
std::sync::atomic::AtomicPtr, with additional advice on how to#[cfg]for it.I feel quite uncertain about whether the paragraph I added to
Arc's documentation should actually be there, as it is a distraction for anyone usingstd. On the other hand, maybe more reminders that no_std exists would benefit the ecosystem.Note:
target_has_atomicis stabilized but not yet documented in the reference.