WIP: introduce WeakFixupFn, start removing Option<*const ()>

This introduce a breaking change starting to modifying all methods that
indicate a realloc by returning a Option(*const()) into stdlib compatible
signatures and variants taking a closure for the fixup.

This commits starts with reserve and shrink methods, more in the following commits.

The `WeakFixupFn` is required for Drain and other iterators which do significant work
in the destructor (possibly reallocating the headervec there). The closure
can be passed along and called when required.

Compatibility note:
When it is not trivially possible to refactor fixup functionality to a closure then
old code can be migrated by:

  let maybe_realloc: Option<*const ()> = {
      let mut opt_ptr = None;
      hv.reserve_with_weakfix(&mut self, 10000, |ptr| opt_ptr = Some(ptr));
      opt_ptr
  };

  // now maybe_realloc is like the old Option<*const ()> return

  if let Some(ptr) = maybe_realloc {
        // fixup code using ptr
  }

Note 2:
do we want legacy wrapper functions that have the old behavior eg.

  #[deprecated("upgrade to the new API")]
  pub fn reserve_legacy(&mut self, additional: usize) -> Option<*const ()> {
      let mut opt_ptr = None;
      self.reserve_with_weakfix(additional, |ptr| opt_ptr = Some(ptr));
      opt_ptr
  };

Author: cehteh

src/lib.rs

@@ -14,6 +14,10 @@ use core::{
 #[cfg(feature = "atomic_append")]
 use core::sync::atomic::{AtomicUsize, Ordering};
 
+/// A closure that becomes called when a `HeaderVec` becomes reallocated.
+/// This is closure is responsible for updating weak nodes.
+pub type WeakFixupFn<'a> = &'a mut dyn FnMut(*const ());
+
 struct HeaderVecHeader<H> {
     head: H,
     capacity: usize,
@@ -220,39 +224,72 @@ impl<H, T> HeaderVec<H, T> {
     }
 
     /// Reserves capacity for at least `additional` more elements to be inserted in the given `HeaderVec`.
-    #[inline(always)]
-    pub fn reserve(&mut self, additional: usize) -> Option<*const ()> {
-        if self.spare_capacity() < additional {
-            let len = self.len_exact();
-            unsafe { self.resize_cold(len.saturating_add(additional), false) }
-        } else {
-            None
-        }
+    #[inline]
+    pub fn reserve(&mut self, additional: usize) {
+        self.reserve_intern(additional, false, None);
+    }
+
+    /// Reserves capacity for at least `additional` more elements to be inserted in the given `HeaderVec`.
+    /// This method must be used when `HeaderVecWeak` are used. It takes a closure that is responsible for
+    /// updating the weak references as additional parameter.
+    #[inline]
+    pub fn reserve_with_weakfix(&mut self, additional: usize, weak_fixup: WeakFixupFn) {
+        self.reserve_intern(additional, false, Some(weak_fixup));
+    }
+
+    /// Reserves capacity for exactly `additional` more elements to be inserted in the given `HeaderVec`.
+    #[inline]
+    pub fn reserve_exact(&mut self, additional: usize) {
+        self.reserve_intern(additional, true, None);
     }
 
     /// Reserves capacity for exactly `additional` more elements to be inserted in the given `HeaderVec`.
+    /// This method must be used when `HeaderVecWeak` are used. It takes a closure that is responsible for
+    /// updating the weak references as additional parameter.
     #[inline]
-    pub fn reserve_exact(&mut self, additional: usize) -> Option<*const ()> {
+    pub fn reserve_exact_with_weakfix(&mut self, additional: usize, weak_fixup: WeakFixupFn) {
+        self.reserve_intern(additional, true, Some(weak_fixup));
+    }
+
+    /// Reserves capacity for at least `additional` more elements to be inserted in the given `HeaderVec`.
+    #[inline(always)]
+    fn reserve_intern(&mut self, additional: usize, exact: bool, weak_fixup: Option<WeakFixupFn>) {
         if self.spare_capacity() < additional {
             let len = self.len_exact();
-            unsafe { self.resize_cold(len.saturating_add(additional), true) }
-        } else {
-            None
+            // using saturating_add here ensures that we get a allocation error instead wrapping over and
+            // allocating a total wrong size
+            unsafe { self.resize_cold(len.saturating_add(additional), exact, weak_fixup) };
         }
     }
 
     /// Shrinks the capacity of the `HeaderVec` to the `min_capacity` or `self.len()`, whichever is larger.
     #[inline]
-    pub fn shrink_to(&mut self, min_capacity: usize) -> Option<*const ()> {
+    pub fn shrink_to(&mut self, min_capacity: usize) {
         let requested_capacity = self.len_exact().max(min_capacity);
-        unsafe { self.resize_cold(requested_capacity, true) }
+        unsafe { self.resize_cold(requested_capacity, true, None) };
+    }
+
+    /// Shrinks the capacity of the `HeaderVec` to the `min_capacity` or `self.len()`, whichever is larger.
+    /// This method must be used when `HeaderVecWeak` are used. It takes a closure that is responsible for
+    /// updating the weak references as additional parameter.
+    #[inline]
+    pub fn shrink_to_with_weakfix(&mut self, min_capacity: usize, weak_fixup: WeakFixupFn) {
+        let requested_capacity = self.len_exact().max(min_capacity);
+        unsafe { self.resize_cold(requested_capacity, true, Some(weak_fixup)) };
+    }
+
+    /// Resizes the vector hold exactly `self.len()` elements.
+    #[inline(always)]
+    pub fn shrink_to_fit(&mut self) {
+        self.shrink_to(0);
     }
 
     /// Resizes the vector hold exactly `self.len()` elements.
+    /// This method must be used when `HeaderVecWeak` are used. It takes a closure that is responsible for
+    /// updating the weak references as additional parameter.
     #[inline(always)]
-    pub fn shrink_to_fit(&mut self) -> Option<*const ()> {
-        let len = self.len_exact();
-        self.shrink_to(len)
+    pub fn shrink_to_fit_with_weakfix(&mut self, weak_fixup: WeakFixupFn) {
+        self.shrink_to_with_weakfix(0, weak_fixup);
     }
 
     /// Resize the vector to least `requested_capacity` elements.
@@ -264,7 +301,12 @@ impl<H, T> HeaderVec<H, T> {
     ///
     /// `requested_capacity` must be greater or equal than `self.len()`
     #[cold]
-    unsafe fn resize_cold(&mut self, requested_capacity: usize, exact: bool) -> Option<*const ()> {
+    unsafe fn resize_cold(
+        &mut self,
+        requested_capacity: usize,
+        exact: bool,
+        weak_fixup: Option<WeakFixupFn>,
+    ) {
         // For efficiency we do only a debug_assert here, this is a internal unsafe function
         // it's contract should be already enforced by the caller which is under our control
         debug_assert!(
@@ -275,7 +317,7 @@ impl<H, T> HeaderVec<H, T> {
 
         // Shortcut when nothing is to be done.
         if requested_capacity == old_capacity {
-            return None;
+            return;
         }
 
         let new_capacity = if requested_capacity > old_capacity {
@@ -319,7 +361,7 @@ impl<H, T> HeaderVec<H, T> {
 
         // Check if the new pointer is different than the old one.
         let previous_pointer = if ptr != self.ptr {
-            // Give the user the old pointer so they can update everything.
+            // Store old pointer for weak_fixup.
             Some(self.ptr())
         } else {
             None
@@ -329,7 +371,8 @@ impl<H, T> HeaderVec<H, T> {
         // And set the new capacity.
         self.header_mut().capacity = new_capacity;
 
-        previous_pointer
+        // Finally run the weak_fixup closure when provided
+        previous_pointer.map(|ptr| weak_fixup.map(|weak_fixup| weak_fixup(ptr)));
     }
 
     /// Adds an item to the end of the list.
@@ -344,7 +387,7 @@ impl<H, T> HeaderVec<H, T> {
             core::ptr::write(self.as_mut_ptr().add(old_len), item);
         }
         self.header_mut().len = new_len.into();
-        previous_pointer
+        todo!("weak_fixup transformartion") // previous_pointer
     }
 
     /// Retains only the elements specified by the predicate.
@@ -497,7 +540,7 @@ impl<H, T: Clone> HeaderVec<H, T> {
         // correct the len
         self.header_mut().len = (self.len_exact() + slice.len()).into();
 
-        previous_pointer
+        todo!("weak_fixup transformartion") // previous_pointer
     }
 }