ferrilab / radium

radium

radium provides abstractions and graceful degradation for behavior that must be shared-mutable, but merely may use atomic instructions to do so.

The primary export is the Radium trait. This is implemented on all symbols in the atomic module, and on their Cell<T> equivalents, and presents the atomic inherent API as a trait. Your code can be generic over Radium, use a stable and consistent API, and permit callers to select atomic or Cell behavior as they need.

The symbols in the atomic module are conditionally present according to the target architecture’s atomic support. As such, code that is portable across targets with varying atomic support cannot use those names directly. Instead, the radium::types module provides names that will always exist, and forward to the corresponding atomic type when it exists and the equivalent Cell<T> type when it does not.

As the cfg(target_has_atomic) compiler attribute is unstable, radium provides the macro radium::if_atomic! to perform conditional compilation based on atomic availability.

This crate is #![no_std]-compatible, and uses no non-core types.

Versioning

Each change of supported target architecture will result in a new minor version. Furthermore, radium is by definition attached to the Rust standard library. As the atomic API evolves, radium will follow it. MSRV raising is always at least a minor-version increase.

If you require a backport of architecture discovery to older Rust versions, please file an issue. We will happily backport upon request, but we do not proactively guarantee support for compilers older than ~six months.

Target Architecture Compatibility

Because the compiler does not expose this information to libraries, radium uses a build script to detect the target architecture and emit its own directives that mark the presence or absence of an atomic integer. We accomplish this by reading the compiler’s target information records and copying the information directly into the build script.

If radium does not work for your architecture, please update the build script to handle your target string and submit a pull request. We write the build script on an as-needed basis; it is not proactively filled with all of the information listed in the compiler.

NOTE: The build script receives information through two variables: TARGET and CARGO_CFG_TARGET_ARCH. The latter is equivalent to the value in cfg!(target_arch =); however, this value does not contain enough information to fully disambiguate the target. The build script attempts to do rudimentary parsing of the env!(TARGET) string; if this does not work for your target, consider using the TARGET_ARCH matcher, or match on the full TARGET string rather than the parse attempt.

---

@kneecaw - https://twitter.com/kneecaw/status/1132695060812849154

Feelin' lazy: Has someone already written a helper trait abstracting operations over AtomicUsize and Cell<usize> for generic code which may not care about atomicity?

@ManishEarth - https://twitter.com/ManishEarth/status/1132706585300496384

no but call the crate radium

(since people didn't care that it was radioactive and used it in everything)

radium's Issues

Version 1.0 and future

The radium API has not changed in some time. I am satisfied with its API as used in bitvec, and it seems that radium has some other dependents who also have not suggested API changes.

Therefore, I propose that we move to version 1.0, and adopt the following versioning policy going forward:

• radium only officially commits to the Rust stable release train. When new APIs are added to the standard library, radium will follow them on a best-effort basis. radium will not gate new APIs behind Cargo features.
• Each of these is a minor-version increase:
  • new standard-library atomic API
  • MSRV lift due to rustc or cargo API changes
  • new supported target architecture
• Changes to target detection or other radium internals are a patch release, if they do not also result in an MSRV lift.

bitvec also tracks the standard-library APIs, and is comfortable tying its MSRV policy to radium's.

If there are no objections remaining by then, I would like to release the main branch as 1.0 on or around 2021 December 25.

please include a file with the license text in the git repo and in published crates

There exist lots of variants of the "MIT" license. Without a license text in the repository, it is not clear which variant is applicable.

For example, the Fedora project recognises over 20 different variants: https://fedoraproject.org/wiki/Licensing:MIT

Please include a license text in this repo, and also add the file to the "include" array in Cargo.toml, so it will be included in the published crates as well.

This is a requirement for applying MIT-style licenses correctly (GitHub license page headers show this, for example here, and it's mentioned on choosealicense.com as well). Most Rust projects licensed under the terms of an MIT license seem to have chosen the MIT License variant that's used by the linked GitHub example (bitvec), which the Fedora Project categorizes as "Modern Style with sublicense".

Unable to build on platforms without atomic types

Some platforms (such as RV32IMC) don't have the atomic types. When trying to build radium for those platforms this error is seen:

error[E0432]: unresolved imports `core::sync::atomic::AtomicBool`, `core::sync::atomic::AtomicI16`, `core::sync::atomic::AtomicI32`, `core::sync::atomic::AtomicI8`, `core::sync::atomic::AtomicIsize`, `core::sync::atomic::AtomicPtr`, `core::sync::atomic::AtomicU16`, `core::sync::atomic::AtomicU32`, `core::sync::atomic::AtomicU8`, `core::sync::atomic::AtomicUsize`
  --> /home/alistair/.cargo/registry/src/github.com-1ecc6299db9ec823/radium-0.3.0/src/lib.rs:29:11
   |
29 |     self, AtomicBool, AtomicI16, AtomicI32, AtomicI8, AtomicIsize, AtomicPtr, AtomicU16, AtomicU32,
   |           ^^^^^^^^^^  ^^^^^^^^^  ^^^^^^^^^  ^^^^^^^^  ^^^^^^^^^^^  ^^^^^^^^^  ^^^^^^^^^  ^^^^^^^^^ no `AtomicU32` in `sync::atomic`
   |           |           |          |          |         |            |          |
   |           |           |          |          |         |            |          no `AtomicU16` in `sync::atomic`
   |           |           |          |          |         |            no `AtomicPtr` in `sync::atomic`
   |           |           |          |          |         no `AtomicIsize` in `sync::atomic`
   |           |           |          |          no `AtomicI8` in `sync::atomic`
   |           |           |          no `AtomicI32` in `sync::atomic`
   |           |           no `AtomicI16` in `sync::atomic`
   |           no `AtomicBool` in `sync::atomic`
30 |     AtomicU8, AtomicUsize, Ordering,
   |     ^^^^^^^^  ^^^^^^^^^^^ no `AtomicUsize` in `sync::atomic`
   |     |
   |     no `AtomicU8` in `sync::atomic`

error: aborting due to previous error

For more information about this error, try `rustc --explain E0432`.
error: could not compile `radium`.

To learn more, run the command again with --verbose.
make: *** [Makefile:141: flash-opentitan] Error 101

Something like this: rust-embedded/heapless#123 should hopefully fix the problem.

Build failure on architecture without atomics

When I add the bitvec dependency to my embedded project (RISCV-32), I get the following compile errors:

error[E0432]: unresolved imports `core::sync::atomic::AtomicBool`, `core::sync::atomic::AtomicI8`, `core::sync::atomic::AtomicU8`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/lib.rs:44:34
   |
44 |         use core::sync::atomic::{AtomicBool, AtomicI8, AtomicU8};
   |                                  ^^^^^^^^^^  ^^^^^^^^  ^^^^^^^^ no `AtomicU8` in `sync::atomic`
   |                                  |           |
   |                                  |           no `AtomicI8` in `sync::atomic`
   |                                  no `AtomicBool` in `sync::atomic`

error[E0432]: unresolved imports `core::sync::atomic::AtomicI16`, `core::sync::atomic::AtomicU16`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/lib.rs:47:34
   |
47 |         use core::sync::atomic::{AtomicI16, AtomicU16};
   |                                  ^^^^^^^^^  ^^^^^^^^^ no `AtomicU16` in `sync::atomic`
   |                                  |
   |                                  no `AtomicI16` in `sync::atomic`

error[E0432]: unresolved imports `core::sync::atomic::AtomicI32`, `core::sync::atomic::AtomicU32`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/lib.rs:50:34
   |
50 |         use core::sync::atomic::{AtomicI32, AtomicU32};
   |                                  ^^^^^^^^^  ^^^^^^^^^ no `AtomicU32` in `sync::atomic`
   |                                  |
   |                                  no `AtomicI32` in `sync::atomic`

error[E0432]: unresolved imports `core::sync::atomic::AtomicI64`, `core::sync::atomic::AtomicU64`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/lib.rs:53:34
   |
53 |         use core::sync::atomic::{AtomicI64, AtomicU64};
   |                                  ^^^^^^^^^  ^^^^^^^^^ no `AtomicU64` in `sync::atomic`
   |                                  |
   |                                  no `AtomicI64` in `sync::atomic`

error[E0432]: unresolved imports `core::sync::atomic::AtomicIsize`, `core::sync::atomic::AtomicPtr`, `core::sync::atomic::AtomicUsize`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/lib.rs:56:34
   |
56 |         use core::sync::atomic::{AtomicIsize, AtomicPtr, AtomicUsize};
   |                                  ^^^^^^^^^^^  ^^^^^^^^^  ^^^^^^^^^^^ no `AtomicUsize` in `sync::atomic`
   |                                  |            |
   |                                  |            no `AtomicPtr` in `sync::atomic`
   |                                  no `AtomicIsize` in `sync::atomic`

error[E0412]: cannot find type `AtomicBool` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:10:43
   |
10 |     if atomic(bool) { core::sync::atomic::AtomicBool }
   |                                           ^^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicI8` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:16:40
   |
16 |     if atomic(8) { core::sync::atomic::AtomicI8 }
   |                                        ^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicU8` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:22:40
   |
22 |     if atomic(8) { core::sync::atomic::AtomicU8 }
   |                                        ^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicI16` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:28:41
   |
28 |     if atomic(16) { core::sync::atomic::AtomicI16 }
   |                                         ^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicU16` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:34:41
   |
34 |     if atomic(16) { core::sync::atomic::AtomicU16 }
   |                                         ^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicI32` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:40:41
   |
40 |     if atomic(32) { core::sync::atomic::AtomicI32 }
   |                                         ^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicU32` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:46:41
   |
46 |     if atomic(32) { core::sync::atomic::AtomicU32 }
   |                                         ^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicI64` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:52:41
   |
52 |     if atomic(64) { core::sync::atomic::AtomicI64 }
   |                                         ^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicU64` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:58:41
   |
58 |     if atomic(64) { core::sync::atomic::AtomicU64 }
   |                                         ^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicIsize` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:64:43
   |
64 |     if atomic(size) { core::sync::atomic::AtomicIsize }
   |                                           ^^^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicUsize` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:70:43
   |
70 |     if atomic(size) { core::sync::atomic::AtomicUsize }
   |                                           ^^^^^^^^^^^ not found in `core::sync::atomic`

error[E0412]: cannot find type `AtomicPtr` in module `core::sync::atomic`
  --> $CARGO_HOME/registry/src/github.com-1ecc6299db9ec823/radium-0.7.0/src/types.rs:76:42
   |
76 |     if atomic(ptr) { core::sync::atomic::AtomicPtr<T> }
   |                                          ^^^^^^^^^ not found in `core::sync::atomic`

As far as I can tell, this crate's purpose is to deal with systems without atomics, so I'm a bit confused.