feat(cordyceps): Initial support for non-CAS targets (#526)

This PR is a first attempt to allow building of `cordyceps` on non-CAS
enabled targets, such as `thumbv6m-none-eabi`/Cortex-M0+/rp2040.

Doing this as a first feature, prior to implementing a non-atomic and
`critical_section` based version of TransferStack, in service of
embassy-rs/embassy#4035.

Rather than making a default-on "CAS" feature, we instead gate on
`cfg(target_has_atomic = "ptr")`, which was [stabilized in
1.60](rust-lang/rust#93824), which currently has
the meaning of "this target has CAS". This automatically gates-out
`TransferStack` and `MpscQueue`, while the "mutable" collections can
still be used.

Author: jamesmunns

.github/workflows/ci.yml

@@ -244,6 +244,26 @@ jobs:
     - name: run Miri tests
       run: just miri cordyceps
 
+  # run no-atomics target tests
+  cordyceps_no_atomics_compat:
+    needs: changed_paths
+    if: needs.changed_paths.outputs.should_skip != 'true' || !fromJSON(needs.changed_paths.outputs.paths_result).cordyceps.should_skip
+    runs-on: ubuntu-latest
+    name: no-atomics compat (cordyceps)
+    steps:
+    - name: install rust toolchain
+      run: rustup show
+    - uses: actions/checkout@v4
+    - name: run check
+      # we add the target HERE instead of in the 'install rust toolchain' step
+      # because we need the `rust-toolchain.toml` file to be checked out, otherwise
+      # the target is only added for `stable`. We could also add this to the
+      # `targets` item in the toolchain file, but that would be a waste for all
+      # other tests.
+      run: |
+        rustup target add thumbv6m-none-eabi
+        cargo check -p cordyceps --target thumbv6m-none-eabi
+
   ### maitake ###
 
   # test with `--no-default-features`
@@ -313,6 +333,7 @@ jobs:
     - docs
     - cordyceps_loom
     - cordyceps_miri
+    - cordyceps_no_atomics_compat
     - maitake_no_default_features
     - maitake_loom
     - maitake_miri

cordyceps/README.md

@@ -86,6 +86,21 @@ than owning those values.
   *must* be pinned in memory; they may not move (or be dropped) while linked
   into an intrusive collection.
 
+## Compatibility
+
+Rudimentary support for targets without CAS (Compare and Swap) atomics, such as
+Cortex-M0+/`thumbv6m-none-eabi`, is provided, however not all structures and
+features may be available.
+
+CAS atomic support is automatically detected with `cfg(target_has_atomic = "ptr")`,
+which notes that a [platform has support] for both load/store operations as well
+as support for CAS atomics.
+
+No crate-level features are necessary to enable/disable structures that require
+CAS atomics.
+
+[platform has support]: https://doc.rust-lang.org/reference/conditional-compilation.html#r-cfg.target_has_atomic
+
 ## about the name
 
 In keeping with Mycelium's fungal naming theme, _Cordyceps_ is a genus of

cordyceps/src/lib.rs

@@ -34,6 +34,9 @@
 //!   [`MpscQueue`]s can be used to efficiently share data from multiple
 //!   concurrent producers with a consumer.
 //!
+//!   This structure is only available if the target supports CAS (Compare and
+//!   Swap) atomics.
+//!
 //! - **[`SortedList`]: a mutable, singly-linked list, with elements stored
 //!   in sorted order.**
 //!
@@ -71,6 +74,9 @@
 //!   A [`TransferStack`] can be used to efficiently transfer ownership of
 //!   resources from multiple producers to a consumer, such as for reuse or
 //!   cleanup.
+//!
+//!   This structure is only available if the target supports CAS (Compare and
+//!   Swap) atomics.
 #[cfg(feature = "alloc")]
 extern crate alloc;
 #[cfg(test)]
@@ -80,18 +86,33 @@ extern crate std;
 pub(crate) mod util;
 
 pub mod list;
-pub mod mpsc_queue;
 pub mod sorted_list;
 pub mod stack;
 
 #[doc(inline)]
 pub use list::List;
 #[doc(inline)]
-pub use mpsc_queue::MpscQueue;
-#[doc(inline)]
 pub use sorted_list::{SortedList, SortedListIter};
 #[doc(inline)]
-pub use stack::{Stack, TransferStack};
+pub use stack::Stack;
+
+//
+// The following items are only available if we have atomics
+//
+#[cfg(target_has_atomic = "ptr")]
+pub mod mpsc_queue;
+
+#[cfg(target_has_atomic = "ptr")]
+pub use has_cas_atomics::*;
+
+#[cfg(target_has_atomic = "ptr")]
+mod has_cas_atomics {
+    #[doc(inline)]
+    pub use crate::mpsc_queue::MpscQueue;
+
+    #[doc(inline)]
+    pub use crate::stack::TransferStack;
+}
 
 pub(crate) mod loom;
 

cordyceps/src/mpsc_queue.rs

@@ -21,6 +21,18 @@ use core::{
     ptr::{self, NonNull},
 };
 
+macro_rules! feature {
+    (
+        #![$meta:meta]
+        $($item:item)*
+    ) => {
+        $(
+            #[cfg($meta)]
+            $item
+        )*
+    }
+}
+
 /// A multi-producer, single-consumer (MPSC) queue, implemented using a
 /// lock-free [intrusive] singly-linked list.
 ///