feat(common): Implement LinkedChunk::clear.

This patch implements `LinkedChunk::clear`. The code from `impl Drop
for LinkedChunk` has been moved inside `Ends::clear`, and replaced by
a simple `self.links.clear()`. In addition, `LinkedChunk::clear` indeed
calls `self.links.clear()` but also resets all fields.

This patch adds the `Clear` variant to `Update`.

This patch updates `AsVector` to emit a `VectorDiff::Clear` on
`Update::Clear`.

Finally, this patch adds the necessary tests.

Author: Hywan

crates/matrix-sdk-common/src/linked_chunk/as_vector.rs

@@ -405,6 +405,11 @@ impl UpdateToVectorDiff {
                     // Exiting the _detaching_ mode.
                     detaching = false;
                 }
+
+                Update::Clear => {
+                    // Let's straightforwardly emit a `VectorDiff::Clear`.
+                    diffs.push(VectorDiff::Clear);
+                }
             }
         }
 
@@ -473,6 +478,7 @@ mod tests {
                 VectorDiff::Remove { index } => {
                     accumulator.remove(index);
                 }
+                VectorDiff::Clear => accumulator.clear(),
                 diff => unimplemented!("{diff:?}"),
             }
         }
@@ -686,14 +692,20 @@ mod tests {
             &[VectorDiff::Insert { index: 14, value: 'z' }],
         );
 
-        drop(linked_chunk);
-        assert!(as_vector.take().is_empty());
-
-        // Finally, ensure the “reconstitued” vector is the one expected.
+        // Ensure the “reconstitued” vector is the one expected.
         assert_eq!(
             accumulator,
             vector!['m', 'a', 'w', 'x', 'y', 'b', 'd', 'i', 'j', 'k', 'l', 'e', 'f', 'g', 'z', 'h']
         );
+
+        // Let's try to clear the linked chunk now.
+        linked_chunk.clear();
+
+        apply_and_assert_eq(&mut accumulator, as_vector.take(), &[VectorDiff::Clear]);
+        assert!(accumulator.is_empty());
+
+        drop(linked_chunk);
+        assert!(as_vector.take().is_empty());
     }
 
     #[test]

crates/matrix-sdk-common/src/linked_chunk/mod.rs

@@ -191,6 +191,36 @@ impl<const CAP: usize, Item, Gap> Ends<CAP, Item, Gap> {
             chunk = chunk.previous_mut()?;
         }
     }
+
+    /// Drop all chunks, and re-create the first one.
+    fn clear(&mut self) {
+        // Loop over all chunks, from the last to the first chunk, and drop them.
+        {
+            // Take the latest chunk.
+            let mut current_chunk_ptr = self.last.or(Some(self.first));
+
+            // As long as we have another chunk…
+            while let Some(chunk_ptr) = current_chunk_ptr {
+                // Fetch the previous chunk pointer.
+                let previous_ptr = unsafe { chunk_ptr.as_ref() }.previous;
+
+                // Re-box the chunk, and let Rust does its job.
+                let _chunk_boxed = unsafe { Box::from_raw(chunk_ptr.as_ptr()) };
+
+                // Update the `current_chunk_ptr`.
+                current_chunk_ptr = previous_ptr;
+            }
+
+            // At this step, all chunks have been dropped, including
+            // `self.first`.
+        }
+
+        // Recreate the first chunk.
+        self.first = Chunk::new_items_leaked(ChunkIdentifierGenerator::FIRST_IDENTIFIER);
+
+        // Reset the last chunk.
+        self.last = None;
+    }
 }
 
 /// The [`LinkedChunk`] structure.
@@ -259,6 +289,24 @@ impl<const CAP: usize, Item, Gap> LinkedChunk<CAP, Item, Gap> {
         }
     }
 
+    /// Clear all the chunks.
+    pub fn clear(&mut self) {
+        // Clear `self.links`.
+        self.links.clear();
+
+        // Clear `self.length`.
+        self.length = 0;
+
+        // Clear `self.chunk_identifier_generator`.
+        self.chunk_identifier_generator = ChunkIdentifierGenerator::new_from_scratch();
+
+        // “Clear” `self.updates`.
+        if let Some(updates) = self.updates.as_mut() {
+            // TODO: Optimisation: Do we want to clear all pending `Update`s in `updates`?
+            updates.push(Update::Clear);
+        }
+    }
+
     /// Get the number of items in this linked chunk.
     #[allow(clippy::len_without_is_empty)]
     pub fn len(&self) -> usize {
@@ -847,27 +895,11 @@ impl<const CAP: usize, Item, Gap> LinkedChunk<CAP, Item, Gap> {
 
 impl<const CAP: usize, Item, Gap> Drop for LinkedChunk<CAP, Item, Gap> {
     fn drop(&mut self) {
-        // Take the latest chunk.
-        let mut current_chunk_ptr = self.links.last.or(Some(self.links.first));
-
-        // As long as we have another chunk…
-        while let Some(chunk_ptr) = current_chunk_ptr {
-            // Disconnect the chunk by updating `previous_chunk.next` pointer.
-            let previous_ptr = unsafe { chunk_ptr.as_ref() }.previous;
-
-            if let Some(mut previous_ptr) = previous_ptr {
-                unsafe { previous_ptr.as_mut() }.next = None;
-            }
-
-            // Re-box the chunk, and let Rust does its job.
-            let _chunk_boxed = unsafe { Box::from_raw(chunk_ptr.as_ptr()) };
-
-            // Update the `current_chunk_ptr`.
-            current_chunk_ptr = previous_ptr;
-        }
-
-        // At this step, all chunks have been dropped, including
-        // `self.first`.
+        // Only clear the links. Calling `Self::clear` would be an error as we don't
+        // want to emit an `Update::Clear` when `self` is dropped. Instead, we only care
+        // about freeing memory correctly. Rust can take care of everything except the
+        // pointers in `self.links`, hence the specific call to `self.links.clear()`.
+        self.links.clear();
     }
 }
 
@@ -1391,7 +1423,10 @@ impl EmptyChunk {
 
 #[cfg(test)]
 mod tests {
-    use std::ops::Not;
+    use std::{
+        ops::Not,
+        sync::{atomic::Ordering, Arc},
+    };
 
     use assert_matches::assert_matches;
 
@@ -2635,4 +2670,49 @@ mod tests {
         assert!(chunks.next().unwrap().is_last_chunk());
         assert!(chunks.next().is_none());
     }
+
+    // Test `LinkedChunk::clear`. This test creates a `LinkedChunk` with `new` to
+    // avoid creating too much confusion with `Update`s. The next test
+    // `test_clear_emit_an_update_clear` uses `new_with_update_history` and only
+    // test `Update::Clear`.
+    #[test]
+    fn test_clear() {
+        let mut linked_chunk = LinkedChunk::<3, Arc<char>, Arc<()>>::new();
+
+        let item = Arc::new('a');
+        let gap = Arc::new(());
+
+        linked_chunk.push_items_back([
+            item.clone(),
+            item.clone(),
+            item.clone(),
+            item.clone(),
+            item.clone(),
+        ]);
+        linked_chunk.push_gap_back(gap.clone());
+        linked_chunk.push_items_back([item.clone()]);
+
+        assert_eq!(Arc::strong_count(&item), 7);
+        assert_eq!(Arc::strong_count(&gap), 2);
+        assert_eq!(linked_chunk.len(), 6);
+        assert_eq!(linked_chunk.chunk_identifier_generator.next.load(Ordering::SeqCst), 3);
+
+        // Now, we can clear the linked chunk and see what happens.
+        linked_chunk.clear();
+
+        assert_eq!(Arc::strong_count(&item), 1);
+        assert_eq!(Arc::strong_count(&gap), 1);
+        assert_eq!(linked_chunk.len(), 0);
+        assert_eq!(linked_chunk.chunk_identifier_generator.next.load(Ordering::SeqCst), 0);
+    }
+
+    #[test]
+    fn test_clear_emit_an_update_clear() {
+        use super::Update::*;
+
+        let mut linked_chunk = LinkedChunk::<3, char, ()>::new_with_update_history();
+        linked_chunk.clear();
+
+        assert_eq!(linked_chunk.updates().unwrap().take(), &[Clear]);
+    }
 }

crates/matrix-sdk-common/src/linked_chunk/updates.rs

@@ -99,6 +99,10 @@ pub enum Update<Item, Gap> {
 
     /// Reattaching items (see [`Self::StartReattachItems`]) is finished.
     EndReattachItems,
+
+    /// All chunks have been cleared, i.e. all items and all gaps have been
+    /// dropped.
+    Clear,
 }
 
 /// A collection of [`Update`]s that can be observed.