CoAlloc: asserts + docs

Author: peter-lyons-kehl

library/alloc/src/collections/vec_deque/spec_from_iter.rs

@@ -38,7 +38,7 @@ impl<T> SpecFromIter<T, IntoIter<T>> for VecDeque<T> {
         iterator.into_vecdeque()
     }
 }
-// ----
+// ---- CoAllocation:
 
 #[allow(unused_braces)]
 impl<T, I, const CO_ALLOC_PREF: CoAllocPref> SpecFromIterCo<T, I>
@@ -48,6 +48,14 @@ where
     [(); { crate::meta_num_slots_global!(CO_ALLOC_PREF) }]:,
 {
     default fn spec_from_iter_co(iterator: I) -> Self {
+        // @FIXME Move the assert to library/alloc/src/macros.rs -> co_alloc_pref!(...) and replace
+        // calls to CO_ALLOC_PREF_META_YES and CO_ALLOC_PREF_META_NO with constants - once
+        // https://github.com/rust-lang/rust/issues/106994 (the ICE) is fixed. Upvote it, please.
+        core::debug_assert!(
+            CO_ALLOC_PREF == crate::CO_ALLOC_PREF_META_YES!()
+                || CO_ALLOC_PREF == crate::CO_ALLOC_PREF_META_NO!(),
+            "CO_ALLOC_PREF must equal to CO_ALLOC_PREF_META_YES!() or CO_ALLOC_PREF_META_NO!(), but it is: {CO_ALLOC_PREF}."
+        );
         // Since converting is O(1) now, just re-use the `Vec` logic for
         // anything where we can't do something extra-special for `VecDeque`,
         // especially as that could save us some monomorphiziation work
@@ -57,7 +65,7 @@ where
 }
 
 // Until we can use feature `specialization`:
-// FIXME macro
+// @FIXME new macro + replace 0 and 1 with META ZERO/ONE
 impl<T> SpecFromIterCo<T, crate::vec::IntoIter<T, Global, 0>> for VecDeque<T, Global, 0> {
     #[inline]
     fn spec_from_iter_co(iterator: crate::vec::IntoIter<T, Global, 0>) -> Self {

library/alloc/src/macros.rs

@@ -127,7 +127,14 @@ macro_rules! __rust_force_expr {
     };
 }
 
-// ----- CoAlloc ICE workaround macro:
+// ----- CoAlloc ICE workaround macro
+//
+// Most of the following code is workaround until we have `generic_const_exprs`. Upvote
+// `https://github.com/rust-lang/rust/issues/76560, please.
+//
+// However, those (commented out) workarounds will compile only once
+// https://github.com/rust-lang/rust/issues/106994 (the ICE) is fixed first. Upvote it, too, please.
+
 /// This "validates" type of a given `const` expression, and it casts it. That helps to prevent mix ups with macros/integer constant values.
 #[doc(hidden)]
 #[macro_export]