Merge pull request #406 from JustForFun88/find_inner

Author: Amanieu

src/raw/mod.rs

@@ -1622,17 +1622,39 @@ impl<A: Allocator + Clone> RawTableInner<A> {
         }
     }
 
-    /// Searches for an element in the table. This uses dynamic dispatch to reduce the amount of
-    /// code generated, but it is eliminated by LLVM optimizations.
+    /// Searches for an element in a table, returning the `index` of the found element.
+    /// This uses dynamic dispatch to reduce the amount of code generated, but it is
+    /// eliminated by LLVM optimizations.
+    ///
+    /// This function does not make any changes to the `data` part of the table, or any
+    /// changes to the `items` or `growth_left` field of the table.
+    ///
+    /// The table must have at least 1 empty `bucket`, otherwise, if the
+    /// `eq: &mut dyn FnMut(usize) -> bool` function does not return `true`,
+    /// this function will also never return (will go into an infinite loop).
     #[inline(always)]
     fn find_inner(&self, hash: u64, eq: &mut dyn FnMut(usize) -> bool) -> Option<usize> {
         let h2_hash = h2(hash);
         let mut probe_seq = self.probe_seq(hash);
 
         loop {
+            // SAFETY:
+            // * `ProbeSeq.pos` cannot be greater than `self.bucket_mask = self.buckets() - 1`
+            //   of the table due to masking with `self.bucket_mask`.
+            //
+            // * Even if `ProbeSeq.pos` returns `position == self.bucket_mask`, it is safe to
+            //   call `Group::load` due to the extended control bytes range, which is
+            //  `self.bucket_mask + 1 + Group::WIDTH` (in fact, this means that the last control
+            //   byte will never be read for the allocated table);
+            //
+            // * Also, even if `RawTableInner` is not already allocated, `ProbeSeq.pos` will
+            //   always return "0" (zero), so Group::load will read unaligned `Group::static_empty()`
+            //   bytes, which is safe (see RawTableInner::new_in).
             let group = unsafe { Group::load(self.ctrl(probe_seq.pos)) };
 
             for bit in group.match_byte(h2_hash) {
+                // This is the same as `(probe_seq.pos + bit) % self.buckets()` because the number
+                // of buckets is a power of two, and `self.bucket_mask = self.buckets() - 1`.
                 let index = (probe_seq.pos + bit) & self.bucket_mask;
 
                 if likely(eq(index)) {