Implement NativeHashtable keyed Lookup and LookupInstanceMethodEntryPoint

Port the runtime VM's NativeHashtable.Enumerator.GetNext() to the
managed reflection mirror. The bucket scan walks entries sorted by low
hashcode, yields candidates whose low byte matches the lookup, and
exits early when the scan passes the target.

Add ReadyToRunReader.LookupInstanceMethodEntryPoint(section,
versionResilientHash, predicate): performs the hashtable probe, decodes
each candidate's signature, asks the caller's predicate to confirm the
full key match, and on success returns the fully-decoded
InstanceMethodPayload (runtime function index + fixup cell list).

Document that Lookup/Enumerator only scan a single bucket and that the
low hashcode byte is a probe filter requiring caller-side key
verification.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jtschuster

src/ILCompiler.Reflection.ReadyToRun.Structural.Assertions/MethodInventory.cs

@@ -205,7 +205,7 @@ private static void AddInstanceMethodEntries(
         IReadOnlyList<ImportSectionSignatures> importSections,
         List<MethodInventoryEntry> output)
     {
-        InstanceMethodEntryPointsTable table = reader.GetInstanceMethodEntryPointsTable(section);
+        InstanceMethodEntryPointsTable table = reader.GetInstanceMethodEntryPointsHashTable(section);
 
         foreach (InstanceMethodEntry entry in table.Entries)
         {

src/ILCompiler.Reflection.ReadyToRun.Structural/InstanceMethodEntryPointsTable.cs

@@ -28,8 +28,43 @@ internal InstanceMethodEntryPointsTable(List<InstanceMethodEntry> entries)
 
     public partial class ReadyToRunReader
     {
-        public InstanceMethodEntryPointsTable GetInstanceMethodEntryPointsTable(ReadyToRunSection section)
+        /// <summary>
+        /// Look up an instance-method entry by version-resilient hashcode and signature predicate.
+        /// Mirrors the runtime VM's pattern of probing the NativeHashtable bucket for entries with
+        /// a matching low-byte hash, decoding each candidate's signature, and asking the caller's
+        /// predicate to confirm the full match (signature equality is decided by the caller because
+        /// only it knows the original key being resolved).
+        /// </summary>
+        /// <returns>The decoded payload for the first matching entry, or <c>null</c> if no entry matches.</returns>
+        public InstanceMethodPayload LookupInstanceMethodEntryPoint(ReadyToRunSection section, int versionResilientHash, Func<MethodSignature, bool> predicate)
         {
+            int sectionOffset = GetOffsetForRVA(section.RelativeVirtualAddress);
+            NativeParser parser = new NativeParser(_nativeReader, (uint)sectionOffset);
+            NativeHashtable hashtable = new NativeHashtable(_nativeReader, parser, (uint)(sectionOffset + section.Size));
+            NativeHashtable.Enumerator enumerator = hashtable.Lookup(versionResilientHash);
+
+            NativeParser entryParser = enumerator.GetNext();
+            while (!entryParser.IsNull())
+            {
+                int payloadOffset = (int)entryParser.Offset;
+                R2RSignatureDecodeResult signature = RawSignatureDecoder.DecodeMethodSignatureWithEndOffset(_nativeReader, payloadOffset, TargetPointerSize);
+                MethodSignature methodSig = MethodSignature.FromSignature(signature.Signature);
+                if (predicate(methodSig))
+                {
+                    (RuntimeFunctionIndex runtimeFunctionIndex, FixupCellListHandle? fixupCellListHandle) = DecodeRuntimeFunctionIdAndFixupCellList(signature.EndOffset);
+                    return new InstanceMethodPayload(signature.Signature, runtimeFunctionIndex, fixupCellListHandle);
+                }
+                entryParser = enumerator.GetNext();
+            }
+
+            return null;
+        }
+
+        public InstanceMethodEntryPointsTable GetInstanceMethodEntryPointsHashTable(ReadyToRunSection section)
+        {
+            if (section.Type != Internal.Runtime.ReadyToRunSectionType.InstanceMethodEntryPoints)
+                throw new InvalidOperationException();
+
             int sectionOffset = GetOffsetForRVA(section.RelativeVirtualAddress);
             NativeParser parser = new NativeParser(_nativeReader, (uint)sectionOffset);
             NativeHashtable hashtable = new NativeHashtable(_nativeReader, parser, (uint)(sectionOffset + section.Size));

src/ILCompiler.Reflection.ReadyToRun/NativeHashtable.cs

@@ -148,10 +148,20 @@ public override string ToString()
             return sb.ToString();
         }
 
-        //
-        // The enumerator does not conform to the regular C# enumerator pattern to avoid paying
-        // its performance penalty (allocation, multiple calls per iteration)
-        //
+        /// <summary>
+        /// Enumerates candidate matches for a hashcode lookup within a <em>single</em> hash bucket.
+        /// <see cref="NativeHashtable.Lookup(int)"/> selects the bucket from the upper bits of the
+        /// hashcode, and this enumerator walks that one bucket looking for entries whose low
+        /// hashcode byte matches the lookup target. Bucket entries are sorted by low hashcode,
+        /// so the scan terminates as soon as it passes the target.
+        ///
+        /// Multiple matches per bucket are normal because the low byte is only an 8-bit probe
+        /// filter; the caller must verify the full key against each entry returned by
+        /// <see cref="GetNext"/>.
+        ///
+        /// The enumerator does not conform to the regular C# enumerator pattern to avoid paying
+        /// its performance penalty (allocation, multiple calls per iteration).
+        /// </summary>
         public struct Enumerator
         {
             private NativeParser _parser;
@@ -164,6 +174,42 @@ internal Enumerator(NativeParser parser, uint endOffset, byte lowHashcode)
                 _endOffset = endOffset;
                 _lowHashcode = lowHashcode;
             }
+
+            /// <summary>
+            /// Advance to the next bucket entry whose low hashcode byte matches the looked-up
+            /// hashcode. Returns a parser positioned at that entry's payload, or a null parser
+            /// when no more matches are available. Multiple matches are possible (low-byte hash
+            /// collisions within the bucket); the caller must verify the full key against each
+            /// returned entry.
+            /// </summary>
+            public NativeParser GetNext()
+            {
+                while (_parser.Offset < _endOffset)
+                {
+                    uint entryStart = _parser.Offset;
+                    byte lowHashcode = _parser.GetByte();
+
+                    if (lowHashcode == _lowHashcode)
+                    {
+                        // Rewind so GetParserFromRelativeOffset re-reads the byte and the
+                        // signed delta, returning a parser at the entry's payload.
+                        _parser.Offset = entryStart;
+                        return _parser.GetParserFromRelativeOffset();
+                    }
+
+                    // The entries are sorted by low hashcode within the bucket, so once we
+                    // see a higher value we can terminate the scan early.
+                    if (lowHashcode > _lowHashcode)
+                    {
+                        _endOffset = _parser.Offset;
+                        break;
+                    }
+
+                    // Skip past the signed relative-offset integer for this non-matching entry.
+                    _parser.GetSigned();
+                }
+                return default;
+            }
         }
 
         public struct AllEntriesEnumerator
@@ -225,6 +271,17 @@ private NativeParser GetParserForBucket(uint bucket, out uint endOffset)
             return new NativeParser(_imageReader, _baseOffset + start);
         }
 
+        /// <summary>
+        /// Begin a hashcode lookup. Selects the single hash bucket addressed by the upper bits
+        /// of <paramref name="hashcode"/> (<c>(hashcode &gt;&gt; 8) &amp; bucketMask</c>) and
+        /// returns an <see cref="Enumerator"/> that walks <em>only that bucket</em>, yielding
+        /// entries whose stored low hashcode byte equals <c>(byte)hashcode</c>.
+        ///
+        /// Because the low byte is just an 8-bit probe filter, multiple matches may be returned
+        /// from the same bucket; the caller is responsible for verifying the full key against
+        /// each candidate. Entries whose full hashcode falls in a different bucket are never
+        /// considered.
+        /// </summary>
         public Enumerator Lookup(int hashcode)
         {
             uint endOffset;