81 lines
3.8 KiB
Markdown
81 lines
3.8 KiB
Markdown
# radium
|
||
|
||
[![Latest Version][version_img]][crate_link]
|
||
[![Documentation][docs_img]][docs_link]
|
||
|
||
`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)
|
||
|
||
<!-- Badges -->
|
||
[crate_link]: https://crates.io/crates/raidum "Crates.io package"
|
||
[docs_img]: https://docs.rs/radium/badge.svg "Radium documentation badge"
|
||
[docs_link]: https://docs.rs/radium "Radium documentation"
|
||
[version_img]: https://img.shields.io/crates/v/radium.svg "Radium version badge"
|
||
[`Cell<T>`]: https://doc.rust-lang.org/core/cell/struct.Cell.html
|
||
[`Radium`]: https://docs.rs/radium/latest/radium/trait.Radium.html
|
||
[`atomic`]: https://doc.rust-lang.org/core/sync/atomic
|
||
[`radium::types`]: https://docs.rs/radium/latest/radium/types
|