doc

Author: pczarn

src/adaptive_hashing.rs

@@ -98,8 +98,10 @@ impl Hasher for AdaptiveHasher {
     #[inline]
     fn write(&mut self, msg: &[u8]) {
         if let Some(ref mut hasher) = self.safe_hasher {
+            // Use safe hashing.
             hasher.write(msg);
         } else {
+            // Use fast hashing.
             let msg_data = unsafe {
                 if msg.len() <= 8 {
                     load_u64_le(msg, msg.len())
@@ -114,8 +116,10 @@ impl Hasher for AdaptiveHasher {
     #[inline]
     fn finish(&self) -> u64 {
         if let Some(ref hasher) = self.safe_hasher {
+            // Use safe hashing.
             hasher.finish()
         } else {
+            // Use fast hashing.
             self.hash
         }
     }

src/adaptive_map.rs

@@ -33,6 +33,16 @@ const LOAD_FACTOR_THRESHOLD: f32 = 0.625;
 // The displacement threshold should be high enough so that even with the maximal load factor,
 // it's very rarely exceeded.
 // As the load approaches 90%, displacements larger than ~ 32 are much more probable.
+// On the other hand, the threshold should be low enough so that the same number of hashes
+// easily fits in the cache and takes a reasonable time to iterate through.
+
+// The load factor threshold should be relatively low, but high enough so that its half is not very
+// low (~ 20%). We choose 62.5%, because it's a simple fraction (5/8), and its half is 31.25%.
+// (When a map is grown, the load factor is halved.)
+
+// TODO: add one-shot hashing for String, str, arrays and other types.
+// TODO: consider adding a limit for the number of fully equal hashes in a probe sequence.
+// Fully equal hashes cause key comparison, which might be a problem for large string keys.
 
 // Avoid problems with private types in public interfaces.
 pub type InternalEntryMut<'a, K: 'a, V: 'a> = InternalEntry<K, V, &'a mut RawTable<K, V>>;
@@ -65,7 +75,7 @@ impl<K, V> SafeguardedSearch<K, V> for HashMap<K, V, AdaptiveState>
         let entry = search_hashed(DerefMapToTable(self), hash, |k| k == key);
         match entry {
             InternalEntry::Occupied { elem } => {
-                // This should compile down to a no-op.
+                // This should compile down to a simple copy.
                 InternalEntry::Occupied { elem: elem.convert_table() }
             }
             InternalEntry::TableIsEmpty => {
@@ -102,12 +112,13 @@ fn safeguard_vacant_entry<'a, K, V>(
     };
     // Copied from FullBucket::displacement.
     let displacement = index.wrapping_sub(hash.inspect() as usize) & (table_capacity - 1);
+    // Check displacement.
     if displacement > DISPLACEMENT_THRESHOLD {
         // Probe sequence is too long.
         // This branch is very unlikely.
         maybe_adapt_to_safe_hashing(elem, key, hash)
     } else {
-        // This should compile down to a no-op.
+        // This should compile down to a simple copy.
         match elem {
             NeqElem(bucket, ib) => {
                 InternalEntry::Vacant {
@@ -125,7 +136,7 @@ fn safeguard_vacant_entry<'a, K, V>(
     }
 }
 
-// Adapt to safe hashing if desirable.
+// Adapt to safe hashing, if desirable.
 #[cold]
 fn maybe_adapt_to_safe_hashing<'a, K, V>(
     elem: VacantEntryState<K, V, DerefMapToTable<'a, K, V, AdaptiveState>>,