Document target_has_atomic

[Mark-Simulacrum]

cc rust-lang/rust#32976

[ehuss]

Thanks! Can you say what the implications are for a target to implement these? Is it mostly that the items in core::sync::atomic are available? Would it make sense to include a link to ../core/sync/atomic/index.html?

Can this also include a small mention that the support for smaller sizes may be implemented by the larger ones? (If that makes sense?)

[ehuss]

Ping @Mark-Simulacrum Just wondering if you can respond to the questions above?

[Mark-Simulacrum]

Yes, it's on my to-do list. Have been quite busy last couple weeks, hoping to get to it soon.

[Mark-Simulacrum]

Sorry for the long delay here. I've pushed up a new version which tries to cover those topics -- and links to the documentation. Hopefully that helps.

[ehuss]

Thanks! Sorry, I pushed a small change to use a relative link before I decided to comment. We use relative links instead of https://doc.rust-lang.org/ so that they work offline and so that the linkchecker can handle them.

[ehuss]

Would it be possible to drop the mention of from_mut? We generally don't cover nightly features in the reference or things that might happen in the future, or delve into the particulars of how the standard library is implemented. We don't have the capacity to track them here, and it isn't relevant to someone working on stable. If target_has_atomic_equal_alignment or something like it is stabilized in the future, then it can be added here.

[Mark-Simulacrum]

Yeah, I have mixed feelings on this, probably should have commented on it myself. I think there's no nice way to describe what this gives you without mentioning from_mut - saying that all APIs are available would be misleading. Maybe the right thing is to drop it here and go add a note to the docs for from_mut though. It's still misleading but perhaps less so.

Does that seem like a reasonable approach?

[ehuss]

Yea, I think a mention in the from_mut docs sounds good. I don't know what the status or history of target_has_atomic_equal_alignment is, though, so I'm not certain what the story is for stabilizing from_mut.

But maybe I'm misunderstanding, as I don't see how from_mut is important. I think it makes sense to say "it makes the corresponding APIs available". That is, if I want to write very portable code, I can write:

#[cfg(target_has_atomic = "64")]
{
    let x = std::sync::atomic::AtomicU64::new(123);
    // ...
}

Perhaps another way to word it would be:

The presence of this cfg is primarily used to check for the availability of the atomic types in [core::sync::atomic] with the corresponding bit width.

[Mark-Simulacrum]

Getting back to this now -- the suggested text/snippet to me implies that

let mut v: u64 = 3;
#[cfg(target_has_atomic = "64")]
{
    let x = std::sync::atomic::AtomicU64::from_mut(&mut v);
    // ...
}

would also be portable, but in practice that's not the case and there's no way (on stable) to conditionally test for that method's existence. And it's pretty easy to make a mistake here, since the cfg and from_mut are true on the common platforms (IIRC, only false on i686 or so?)

[ehuss]

Since from_mut is still unstable, I still think it should not be mentioned in the reference. I wasn't trying to imply that every function and method would be available. Just that the primary use case for target_has_atomic is to detect the presence of the types (AtomicU8, AtomicU16, …).

from_mut isn't available on stable, and I would think that target_has_atomic_equal_alignment (or something similar) would be good to stabilize beforehand. And the requirement of target_has_atomic_equal_alignment should be made clear in the documentation of the from_mut documentation (and anything else that requires it). In theory, something like the portability lint would catch mistakes like your example.

[ehuss]

@Mark-Simulacrum Just checking in again on this. I was wondering if you would be ok with removing the discussion around from_mut? I think that means just removing everything in the paragraph starting with with the exception of…. We generally avoid mentioning any unstable bits in the reference. When from_mut and/or target_has_atomic_equal_alignment is stabilized in the future, that information can be added to the reference as appropriate.

[Mark-Simulacrum]

Oh I completely forgot about this. Yeah, I'm OK removing that for now. I'll push a commit to that effect in a moment.

[Mark-Simulacrum]

@ehuss pushed the adjustment to just drop the mention of the unstable API.

[ehuss]

Thanks! ❤️