CoAlloc: Removed co_alloc_metadata_num_slots(). Added docs.

Author: peter-lyons-kehl

library/alloc/src/boxed.rs

@@ -749,7 +749,7 @@ impl<T> Box<[T]> {
 
 impl<T, A: Allocator> Box<[T], A>
 where
-    [(); core::alloc::co_alloc_metadata_num_slots::<A>()]:,
+    [(); core::alloc::co_alloc_metadata_num_slots_with_preference::<A>(false)]:,
 {
     /// Constructs a new boxed slice with uninitialized contents in the provided allocator.
     ///
@@ -778,11 +778,7 @@ where
     // #[unstable(feature = "new_uninit", issue = "63291")]
     #[must_use]
     #[allow(unused_braces)]
-    pub fn new_uninit_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A>
-    where
-        // false = no need for co-alloc metadata, since it would get lost once converted to Box.
-        [(); core::alloc::co_alloc_metadata_num_slots_with_preference::<A>(false)]:,
-    {
+    pub fn new_uninit_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A> {
         unsafe { RawVec::<T, A, false>::with_capacity_in(len, alloc).into_box(len) }
     }
 
@@ -811,11 +807,7 @@ where
     // #[unstable(feature = "new_uninit", issue = "63291")]
     #[must_use]
     #[allow(unused_braces)]
-    pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A>
-    where
-        // false = no need for co-alloc metadata, since it would get lost once converted to Box.
-        [(); core::alloc::co_alloc_metadata_num_slots_with_preference::<A>(false)]:,
-    {
+    pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit<T>], A> {
         unsafe { RawVec::<T, A, false>::with_capacity_zeroed_in(len, alloc).into_box(len) }
     }
 }

library/core/src/alloc/mod.rs

@@ -65,13 +65,15 @@ impl fmt::Display for AllocError {
     }
 }
 
+/// (Non-Null) Pointer and coallocation metadata.
 #[unstable(feature = "global_co_alloc_meta", issue = "none")]
 #[allow(missing_debug_implementations)]
 pub struct PtrAndMeta {
     pub ptr: NonNull<u8>,
     pub meta: GlobalCoAllocMeta,
 }
 
+/// (NonNull) Slice and coallocation metadata.
 #[unstable(feature = "global_co_alloc_meta", issue = "none")]
 #[allow(missing_debug_implementations)]
 /// Used for results (from `CoAllocator`'s functions, where applicable).
@@ -89,24 +91,15 @@ macro_rules! SHORT_TERM_VEC_PREFERS_COOP {
     };
 }
 
+/// `Result` of `SliceAndMeta` or `AllocError`.
 #[unstable(feature = "global_co_alloc_meta", issue = "none")]
 #[allow(missing_debug_implementations)]
 pub type SliceAndMetaResult = Result<SliceAndMeta, AllocError>;
 
-#[unstable(feature = "global_co_alloc", issue = "none")]
-pub const fn co_alloc_metadata_num_slots<A: Allocator>() -> usize {
-    // @FIXME later
-    if false {
-        panic!(
-            "FIXME - consider replacing co_alloc_metadata_num_slots() with co_alloc_metadata_num_slots_with_preference(bool), and adding const flags as appropriate."
-        );
-    }
-    if A::IS_CO_ALLOCATOR { 1 } else { 0 }
-}
-
-#[unstable(feature = "global_co_alloc", issue = "none")]
+/// Return 0 or 1, indicating whether to use coallocation metadata or not.
 /// Param `coop_preferred` - if false, then this returns `0`, regardless of
 /// whether allocator `A` is cooperative.
+#[unstable(feature = "global_co_alloc", issue = "none")]
 pub const fn co_alloc_metadata_num_slots_with_preference<A: Allocator>(
     coop_preferred: bool,
 ) -> usize {