util: add portable_atomic_unstable_coerce_unsized cfg option

[brody2consult]

(with some minor CI & documentation updates)

Adapted from Rust std library - this adds automatic casting to Arc as discussed in issue #143 behind portable_atomic_unstable_coerce_unsized cfg option ... of course this would only work with Rust nightly until custom unsized coercions is stabilized ref: rust-lang/rust#18598

MOTIVATION: enable more straight-forward support for rustls on no-std targets without built-in atomics ref: rustls/rustls#2068 (using an internal alias as an easy way to select between alloc::sync::Arc vs portable_atomic_util::Arc as needed) as @brodycj has proposed now in rustls/rustls#2200

P.S. IIRC I think I have seen a lot of the smaller embedded CPU targets more likely to be built with Rust nightly anyways, thinking it would be much more straightforward to add this coercion support than one of the other alternative workaround ideas discussed above.

ALTERNATIVE SOLUTIONS CONSIDERED for rustls/rustls#2068:

• use internal aliasing of Arc to alloc::rc::Rc, if needed to support a target with no built-in atomics - I have already tried this solution in ALT DRAFT RFC: add option to use alloc::rc::Rc for no-std targets w/o built-in atomic ops - INITIAL HACK rustls/rustls#2088 ... this seems to suffer from multiple forms of API mangling with ugly API trait macros to conditionally include Send & Sync traits depending on using Arc vs Rc
• add & support use of utility functions or macros to support multiple casting workarounds - I have started working on this kind of workaround and have found the required API changes to be a bit messy & potentially hard-to-document

I think this proposal should be much, much cleaner & more straightforward than either of the alternative solutions above.

CI TESTING - UPDATED:

• added one more step to test with portable_atomic_unstable_coerce_unsized cfg option
• skip testing with --cfg portable_atomic_test_outline_atomics_detect_false on arm-linux-androideabi, with note that this was removed due to an apparent issue I encountered between Rust nightly & QEmu in CI testing (note that there seems to be testing of --cfg portable_atomic_test_outline_atomics_detect_false with armv5te among some other targets so I suspect & hope that this should be sufficient to test --cfg portable_atomic_test_outline_atomics_detect_false)

In case we DO need to preserve testing with --cfg portable_atomic_test_outline_atomics_detect_false on arm-linux-androideabi, any pointers that could help me resolve the CI testing issue I encountered would be extremely helpful.

---

TODO ITEMS - UPDATED:

• TODO items are tracked by XXX TODO & XXX @brodycj (TODO) comments.
• I would like to raise separate PRs for some TODO improvements as already discussed in the XXX / TODO comments.

I have raised PR #199 to update a test label & think I have been able to resolve all other TODO items required for this proposal.

[taiki-e]

Is there any plan regarding the stabilization of this feature? I do not want to rely unconditionally on a feature that is forever unstable or expected to change many times in the future.

[brody2consult]

Is there any plan regarding the stabilization of this feature?

rust-lang/rust#18598 - unfortunately it seems to be held up on what looks like a somewhat theoretical discussion:

Things to consider prior to stabilization

• Interaction with pin, see this internals thread and Pin is unsound due to transitive effects of CoerceUnsized #68015 for details.

Would you be open to adding this behind a new, optional feature?

[taiki-e]

Would you be open to adding this behind a new, optional feature?

Cargo feature would be a bad idea for unstable ones. cfg like tokio_unstable is okay.

[brody2consult]

cfg like tokio_unstable is okay.

Makes sense to me. The one thing is that this would make rustls non-atomic-ptr support I proposed in rustls/rustls#2200 a little harder to build, test, and document. Any ideas or pointers you may have would be very much appreciated. (Working with Rust embedded is still pretty new for me.)

/cc @bjoernQ

[brody2consult]

very minor rewording of some test comments

[taiki-e]

LGTM!

[brody2consult]

Thanks please let me know if you need anything else for this

[taiki-e]

Published in portable-atomic-util 0.2.4. Thanks @brodycj!

[brody2consult]

@taiki-e thanks to you for your part in making & publishing this update - so much appreciated for this now unblocking my work in rustls/rustls#2200 🎉

---

P.S. You may see the one-time sponsorship I sent, in appreciation