[WeakLookupTable] Fix precondition for maximum capacity

Also, added comments for justifying every unsafe '&+' and '&*' operation.

Author: rintaro

Sources/SwiftSyntax/WeakLookupTable.swift

@@ -76,23 +76,28 @@ class WeakLookupTable<Element: Identifiable & AnyObject> {
   /// '_minimalBucketCount(for: capacity)'
   private static func _bucketCount(for capacity: Int,
                                    from current: Int = 2) -> Int {
-    // Make sure it's representable.
-    precondition(capacity <= (Int.max >> 1) + 1)
     // Bucket count must always be power of 2.
     precondition((current & (current - 1)) == 0)
     // Minimum is 2 to guarantee at least 1 hole.
     precondition(current >= 2)
 
     let minimalBucketCount = _minimalBucketCount(for: capacity)
+
+    // Make sure it's representable. If 'minimalBucketCount' here is over
+    // 0x4000_..., the bucket count must be 0x8000_... thus overflows.
+    precondition(minimalBucketCount <= (Int.max >> 1) + 1)
+
     var bucketCount = current
     while bucketCount < minimalBucketCount {
+      // '&*=' for performance. Guaranteed by above 'precondition()'.
       bucketCount &*= 2
     }
     return bucketCount
   }
 
   private var _bucketMask: Int {
     @inline(__always) get {
+      // '&-' for performance. We know 'bucketCount >= 2'.
       return bucketCount &- 1
     }
   }
@@ -116,6 +121,7 @@ class WeakLookupTable<Element: Identifiable & AnyObject> {
       if obj.id == id {
         return (bucket, true)
       }
+      // '&+' for performance. 'bucketCount' is 0x4000_... or below.
       bucket = (bucket &+ 1) & _bucketMask
     }
   }
@@ -157,6 +163,7 @@ class WeakLookupTable<Element: Identifiable & AnyObject> {
   private func _countOccupiedBuckets() -> Int {
     var count = 0
     for i in 0 ..< bucketCount where buckets[i].value != nil {
+      // '&+=' for performance. 'bucketCount' is 0x4000_... or below.
       count &+= 1
     }
     return count
@@ -165,13 +172,18 @@ class WeakLookupTable<Element: Identifiable & AnyObject> {
   /// Reserves enough space to store a single new object. Returns true if
   /// resizing happened.
   private func _ensurePlusOneCapacity() -> Bool {
+    // '&+' for performance. 'estimatedCount' is always less than 'bucketCount'
+    // which is 0x4000_... or below.
     if bucketCount >= WeakLookupTable<Element>
                         ._minimalBucketCount(for: estimatedCount &+ 1) {
       return false
     }
 
     // Slow path.
     estimatedCount = _countOccupiedBuckets()
+    // '&+' for performance. We know 'estimatedCount' derived by
+    // '_countOccupiedBuckets()' is equal to or less than previous
+    // 'estimatedCount'.
     return reserveCapacity(estimatedCount &+ 1)
   }
 
@@ -187,6 +199,7 @@ class WeakLookupTable<Element: Identifiable & AnyObject> {
       pos = _findHole(obj.id).pos
     }
     buckets[pos].value = obj
+    // '&+=' for performance. '_ensurePlusOneCapacity()' ensures it's safe.
     estimatedCount &+= 1
     return true
   }
@@ -205,6 +218,7 @@ class WeakLookupTable<Element: Identifiable & AnyObject> {
       if let obj = buckets[bucket].value, obj.id == id {
         return obj
       }
+      // '&+' for performance. 'bucketCount' is 0x4000_... or below.
       bucket = (bucket &+ 1) & _bucketMask
     } while bucket != idealBucket