Auto merge of #405 - JustForFun88:find_insert_slot, r=Amanieu

Doc `RawTableInner::find_insert_slot` and also make it unsafe

Made this function unsafe, as it is possible to use the index returned by this function unsafely. Here are two functions that confirm the documentation I made:
```rust
#[test]
fn test_infinite_loop() {
	use ::alloc::vec::Vec;
	let mut table: RawTable<u16> = RawTable::with_capacity(20);

	assert_eq!(table.capacity(), 28);
	assert_eq!(table.buckets(), 32);
	for i in 0..table.buckets() {
		unsafe {
			let bucket_index = table.table.find_insert_slot(i as u64);

			table.table.set_ctrl_h2(bucket_index, i as u64);
			table.table.items += 1;

			table.bucket(bucket_index).write(i as u16);
		}
	}

	let vec = unsafe { table.iter().map(|x| x.read()).collect::<Vec<_>>() };

	assert_eq!(vec, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31]);

	// this never return
	let _bucket_index = unsafe { table.table.find_insert_slot(32) };
}

#[test]
fn test_undefined_behavior() {
	use ::alloc::vec::Vec;

	let mut table: RawTable<u16> = RawTable::with_capacity(3);

	assert_eq!(table.capacity(), 3);
	assert_eq!(table.buckets(), 4);
	for i in 0..3 {
		table.insert(i, i as u16, |i| *i as u64);
	}

	assert_eq!(table.table.items, 3);
	assert_eq!(table.table.growth_left, 0);

	let bucket_index = unsafe { table.table.find_insert_slot(3_u64) };

	assert_eq!(bucket_index, 3);

	unsafe {
		table.table.set_ctrl_h2(bucket_index, 3_u64);
		table.table.items += 1;
		table.bucket(bucket_index).write(3_u16);
	}

	let vec = unsafe { table.iter().map(|x| x.read()).collect::<Vec<_>>() };

	assert_eq!(vec, [0, 1, 2, 3]);
	let bucket_index = unsafe { table.table.find_insert_slot(4_u64) };
	assert_eq!(bucket_index, 4);
}
```

Author: bors

src/raw/mod.rs

@@ -1586,16 +1586,48 @@ impl<A: Allocator + Clone> RawTableInner<A> {
     }
 
     /// Searches for an empty or deleted bucket which is suitable for inserting
-    /// a new element.
+    /// a new element, returning the `index` for the new [`Bucket`].
     ///
-    /// There must be at least 1 empty bucket in the table.
+    /// 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 or deleted `bucket`, otherwise this function
+    /// will never return (will go into an infinite loop) for tables larger than the group
+    /// width, or return an index outside of the table indices range if the table is less
+    /// than the group width.
+    ///
+    /// # Note
+    ///
+    /// Calling this function is always safe, but attempting to write data at
+    /// the index returned by this function when the table is less than the group width
+    /// and if there was not at least one empty bucket in the table will cause immediate
+    /// [`undefined behavior`]. This is because in this case the function will return
+    /// `self.bucket_mask + 1` as an index due to the trailing EMPTY control bytes outside
+    /// the table range.
+    ///
+    /// [`undefined behavior`]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
     #[inline]
     fn find_insert_slot(&self, hash: u64) -> usize {
         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` and also because mumber of
+            //   buckets is a power of two (see comment for masking below).
+            //
+            // * 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).
             unsafe {
                 let group = Group::load(self.ctrl(probe_seq.pos));
                 if let Some(bit) = group.match_empty_or_deleted().lowest_set_bit() {
+                    // 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 result = (probe_seq.pos + bit) & self.bucket_mask;
 
                     // In tables smaller than the group width, trailing control
@@ -1607,9 +1639,26 @@ impl<A: Allocator + Clone> RawTableInner<A> {
                     // table. This second scan is guaranteed to find an empty
                     // slot (due to the load factor) before hitting the trailing
                     // control bytes (containing EMPTY).
+                    //
+                    // SAFETY: The `result` is guaranteed to be in range `0..self.bucket_mask`
+                    // due to masking with `self.bucket_mask`
                     if unlikely(self.is_bucket_full(result)) {
                         debug_assert!(self.bucket_mask < Group::WIDTH);
                         debug_assert_ne!(probe_seq.pos, 0);
+                        // SAFETY:
+                        //
+                        // * We are in range and `ptr = self.ctrl(0)` are valid for reads
+                        //   and properly aligned, because the table is already allocated
+                        //   (see `TableLayout::calculate_layout_for` and `ptr::read`);
+                        //
+                        // * For tables larger than the group width, we will never end up in the given
+                        //   branch, since `(probe_seq.pos + bit) & self.bucket_mask` cannot return a
+                        //   full bucket index. For tables smaller than the group width, calling the
+                        //   `lowest_set_bit_nonzero` function (when `nightly` feature enabled) is also
+                        //   safe, as the trailing control bytes outside the range of the table are filled
+                        //   with EMPTY bytes, so this second scan either finds an empty slot (due to the
+                        //   load factor) or hits the trailing control bytes (containing EMPTY). See
+                        //   `intrinsics::cttz_nonzero` for more information.
                         return Group::load_aligned(self.ctrl(0))
                             .match_empty_or_deleted()
                             .lowest_set_bit_nonzero();