Optimize ImmutableHashSet<T>.SetEquals to avoid unnecessary allocations

[aw0lid]

Fixes#90986, Part of #127279

Summary

ImmutableHashSet<T>.SetEquals always creates a new intermediate HashSet<T> for the other collection, leading to avoidable allocations and GC pressure, especially for large datasets

Optimization Logic

• O(1) Pre-Scan: Immediately returns false if other is an ICollection with a smaller Count, avoiding any overhead.
• Fast-Path Pattern Matching: Detects ImmutableHashSet<T> and HashSet<T> to bypass intermediate allocations.
• Comparer Guard: Validates EqualityComparer compatibility before triggering fast paths to ensure logical consistency.
• Short-Circuit Validation: Re-validates Count within specialized paths for an immediate exit before $O(n)$ enumeration.
• Reverse-Lookup Strategy: An architectural shift where the ImmutableHashSet (The Source) iterates and queries the other collection if was Hashset. This leverages the O(1) lookup of the HashSet instead of the O(log N) lookup of the immutable tree.
• Zero-Allocation Execution: Direct iteration over compatible collections, eliminating the costly new HashSet<T>(other) fallback.
• Deferred fallback: Reserves the expensive allocation solely for general IEnumerable types.

Click to expand Benchmark Source Code

usingBenchmarkDotNet.Attributes;usingBenchmarkDotNet.Order;usingBenchmarkDotNet.Running;usingSystem;usingSystem.Collections.Generic;usingSystem.Collections.Immutable;usingSystem.Linq;namespaceImmutableHashSetBenchmarks{[MemoryDiagnoser][Orderer(SummaryOrderPolicy.FastestToSlowest)][RankColumn]publicclassImmutableHashSetSetEqualsBenchmark_Int{privateImmutableHashSet<int>_sourceSet=null!;privateImmutableHashSet<int>_immutableHashSetEqual=null!;privateHashSet<int>_bclHashSetEqual=null!;privateList<int>_listEqual=null!;privateIEnumerable<int>_linqSelectEqual=null!;privateint[]_arrayEqual=null!;privateList<int>_listLastDiff=null!;privateList<int>_listSmaller=null!;privateImmutableHashSet<int>_immutableLarger=null!;privateint[]_smallerArray=null!;privateHashSet<int>_smallerHashSetDiffComparer=null!;// Worst case: same count, last element differentprivateImmutableHashSet<int>_immutableHashSetLastDiff=null!;privateHashSet<int>_bclHashSetLastDiff=null!;privateList<int>_listWithDuplicates=null!;privateList<int>_listWithDuplicatesMatch=null!;// Different comparers (fallback path)privateHashSet<int>_bclHashSetDiffComparer=null!;// Count mismatch early exitprivateImmutableHashSet<int>_immutableHashSetSmaller=null!;privateHashSet<int>_bclHashSetSmaller=null!;// Lazy enumerable for worst caseprivateIEnumerable<int>_lazyEnumerableLastDiff=null!;[Params(100000)]publicintSize{get;set;}[GlobalSetup]publicvoidSetup(){varelements=Enumerable.Range(0,Size).ToList();varelementsWithLastDiff=Enumerable.Range(0,Size-1).Concat(new[]{Size+1000}).ToList();varsmallerElements=Enumerable.Range(0,Size/2).ToList();varduplicates=Enumerable.Repeat(1,Size).ToList();varsmallerList=newList<int>();for(inti=0;i<Size-1;i++)smallerList.Add(i);_sourceSet=ImmutableHashSet.CreateRange(elements);_immutableHashSetEqual=ImmutableHashSet.CreateRange(elements);_bclHashSetEqual=newHashSet<int>(elements);_listEqual=elements;_linqSelectEqual=elements.Select(x =>x);// Lazy LINQ enumerable_arrayEqual=elements.ToArray();_immutableHashSetLastDiff=ImmutableHashSet.CreateRange(elementsWithLastDiff);_bclHashSetLastDiff=newHashSet<int>(elementsWithLastDiff);_listLastDiff=elementsWithLastDiff;_bclHashSetDiffComparer=newHashSet<int>(elements,newReverseComparer<int>());_immutableHashSetSmaller=ImmutableHashSet.CreateRange(smallerElements);_bclHashSetSmaller=newHashSet<int>(smallerElements);_lazyEnumerableLastDiff=elementsWithLastDiff.Select(x =>x);_immutableLarger=ImmutableHashSet.CreateRange(elements.Concat(new[]{-1}));_listWithDuplicates=duplicates;_listWithDuplicatesMatch=elements.Concat(elements).ToList();// Matches source but with duplicates_listSmaller=smallerList;_smallerArray=Enumerable.Range(0,Size-1).ToArray();_smallerHashSetDiffComparer=newHashSet<int>(_listSmaller,newReverseComparer<int>());}
#region Fast Path: Same Type and Comparer (Optimized)
[Benchmark(Description="ImmutableHashSet (Match - Same Comparer)")]publicboolCase_ImmutableHashSet_Match()=>_sourceSet.SetEquals(_immutableHashSetEqual);[Benchmark(Description="BCL HashSet (Match - Same Comparer)")]publicboolCase_BclHashSet_Match()=>_sourceSet.SetEquals(_bclHashSetEqual);[Benchmark(Description="ImmutableHashSet (Mismatch - Same Count)")]publicboolCase_ImmutableHashSet_LastDiff()=>_sourceSet.SetEquals(_immutableHashSetLastDiff);[Benchmark(Description="Case 04: BCL HashSet (Mismatch - Same Count)")]publicboolCase_BclHashSet_LastDiff()=>_sourceSet.SetEquals(_bclHashSetLastDiff);
#endregion
#region Early Exit: Count Mismatch
[Benchmark(Description="ImmutableHashSet (Smaller Count)")]publicboolCase_ImmutableHashSet_SmallerCount()=>_sourceSet.SetEquals(_immutableHashSetSmaller);[Benchmark(Description="BCL HashSet (Smaller Count)")]publicboolCase_BclHashSet_SmallerCount()=>_sourceSet.SetEquals(_bclHashSetSmaller);[Benchmark(Description="Array (Smaller Count)")]publicboolCase_SmallerCollection_EarlyExit(){return_sourceSet.SetEquals(_smallerArray);}
#endregion
#region Fallback Path: Different Comparer
[Benchmark(Description="HashSet (Different Comparer)")]publicboolCase_HashSet_DifferentComparer()=>_sourceSet.SetEquals(_bclHashSetDiffComparer);[Benchmark(Description="HashSet (Smaller Count - Different Comparer)")]publicboolCase_HashSet_SmallerCount_DiffComparer()=>_sourceSet.SetEquals(_smallerHashSetDiffComparer);
#endregion
#region Fallback Path: Non-Set Collections (IEnumerable/ICollection)
[Benchmark(Description="List (Match - Fallback)")]publicboolCase_List_Match()=>_sourceSet.SetEquals(_listEqual);[Benchmark(Description="LINQ (Mismatch - Lazy IEnumerable)")]publicboolCase_LazyEnumerable_LastDiff()=>_sourceSet.SetEquals(_lazyEnumerableLastDiff);[Benchmark(Description="LINQ (Match - Lazy IEnumerable)")]publicboolCase_LazyEnumerable_Match()=>_sourceSet.SetEquals(_linqSelectEqual);[Benchmark(Description="List (Last Diff - Fallback)")]publicboolCase_List_LastDiff()=>_sourceSet.SetEquals(_listLastDiff);[Benchmark(Description="Array (Match - Fallback)")]publicboolCase_Array_Match()=>_sourceSet.SetEquals(_arrayEqual);[Benchmark(Description="ImmutableHashSet (Larger Count)")]publicboolCase_LargerCount()=>_sourceSet.SetEquals(_immutableLarger);
#endregion
#region Handling Duplicates (Fallback Path)
[Benchmark(Description="List with Duplicates (Mismatch)")]publicboolCase_List_Duplicates_Mismatch()=>_sourceSet.SetEquals(_listWithDuplicates);[Benchmark(Description="List with Duplicates (Match)")]publicboolCase_List_Duplicates_Match()=>_sourceSet.SetEquals(_listWithDuplicatesMatch);
#endregion
}publicclassReverseComparer<T>:IEqualityComparer<T>whereT:IComparable<T>{publicboolEquals(T?x,T?y){if(xisnull&&yisnull)returntrue;if(xisnull||yisnull)returnfalse;returnx.CompareTo(y)==0;}publicintGetHashCode(T?obj){returnobj?.GetHashCode()??0;}}publicclassProgram{publicstaticvoidMain(string[]args){BenchmarkRunner.Run<ImmutableHashSetSetEqualsBenchmark_Int>();}}}

Click to expand Benchmark Results

Benchmark Results (Before Optimization)

Method	Size	Mean	Error	StdDev	Rank	Gen0	Gen1	Gen2	Allocated
'BCL HashSet (Smaller Count)'	100000	313.8 us	6.01 us	6.43 us	1	15.6250	15.6250	15.6250	818.33 KB
'Array (Smaller Count)'	100000	647.9 us	11.20 us	11.50 us	2	26.3672	26.3672	26.3672	1697.7 KB
'List with Duplicates (Mismatch)'	100000	954.1 us	18.77 us	41.60 us	3	31.2500	31.2500	31.2500	1697.77 KB
' HashSet (Smaller Count - Different Comparer)'	100000	1,449.3 us	28.65 us	74.46 us	4	41.0156	41.0156	41.0156	1697.8 KB
' ImmutableHashSet (Smaller Count)'	100000	4,733.2 us	74.18 us	69.39 us	5	23.4375	23.4375	23.4375	818.58 KB
' BCL HashSet (Match - Same Comparer)'	100000	7,084.0 us	65.02 us	57.64 us	6	54.6875	54.6875	54.6875	1697.9 KB
'Array (Match - Fallback)'	100000	7,821.7 us	30.71 us	27.23 us	7	46.8750	46.8750	46.8750	1697.86 KB
'List (Match - Fallback)'	100000	8,428.4 us	30.82 us	28.83 us	8	46.8750	46.8750	46.8750	1697.9 KB
'BCL HashSet (Mismatch - Same Count)'	100000	8,636.3 us	52.37 us	46.42 us	8	46.8750	46.8750	46.8750	1697.86 KB
'List (Last Diff - Fallback)'	100000	9,172.5 us	35.85 us	33.54 us	9	46.8750	46.8750	46.8750	1697.9 KB
'List with Duplicates (Match)'	100000	9,310.2 us	128.11 us	119.83 us	9	109.3750	109.3750	109.3750	3521.42 KB
' ImmutableHashSet (Larger Count)'	100000	9,477.3 us	141.55 us	125.48 us	9	46.8750	46.8750	46.8750	1697.89 KB
' HashSet (Different Comparer)'	100000	9,839.2 us	99.14 us	87.88 us	9	46.8750	46.8750	46.8750	1697.79 KB
'LINQ (Mismatch - Lazy IEnumerable)'	100000	11,274.4 us	63.77 us	56.53 us	10	296.8750	156.2500	156.2500	4717.23 KB
'LINQ (Match - Lazy IEnumerable)'	100000	11,341.5 us	69.37 us	61.49 us	10	296.8750	156.2500	156.2500	4717.23 KB
'ImmutableHashSet (Mismatch - Same Count)'	100000	17,015.5 us	170.03 us	150.73 us	11	31.2500	31.2500	31.2500	1697.88 KB
'ImmutableHashSet (Match - Same Comparer)'	100000	17,410.2 us	334.48 us	312.87 us	11	31.2500	31.2500	31.2500	1697.87 KB

---

Benchmark Results (After Optimization)

Method	Size	Mean	Error	StdDev	Rank	Gen0	Gen1	Gen2	Allocated
'ImmutableHashSet (Smaller Count)'	100000	2.300 ns	0.0478 ns	0.0447 ns	1	-	-	-	-
'ImmutableHashSet (Larger Count)'	100000	2.328 ns	0.0650 ns	0.0576 ns	1	-	-	-	-
'BCL HashSet (Smaller Count)'	100000	2.595 ns	0.0524 ns	0.0491 ns	2	-	-	-	-
'HashSet (Smaller Count - Different Comparer)'	100000	2.644 ns	0.0464 ns	0.0411 ns	2	-	-	-	-
'Array (Smaller Count)'	100000	2.711 ns	0.0568 ns	0.0504 ns	2	-	-	-	-
'List with Duplicates (Mismatch)'	100000	794,876.698 ns	15,781.0452 ns	35,941.4284 ns	3	31.2500	31.2500	31.2500	1738498 B
'List (Last Diff - Fallback)'	100000	4,722,211.915 ns	55,323.2393 ns	51,749.3924 ns	4	54.6875	54.6875	54.6875	1738698 B
'List (Match - Fallback)'	100000	4,778,905.952 ns	33,894.4095 ns	28,303.3670 ns	4	54.6875	54.6875	54.6875	1738688 B
'List with Duplicates (Match)'	100000	5,517,422.167 ns	110,159.9473 ns	171,505.7803 ns	5	93.7500	93.7500	93.7500	3605853 B
'BCL HashSet (Match - Same Comparer)'	100000	5,576,721.937 ns	45,754.5403 ns	38,207.1134 ns	5	-	-	-	-
'Case 04: BCL HashSet (Mismatch - Same Count)'	100000	5,640,651.163 ns	64,526.5199 ns	60,358.1468 ns	5	-	-	-	-
'LINQ (Mismatch - Lazy IEnumerable)'	100000	6,406,188.227 ns	132,260.6999 ns	379,480.7689 ns	6	281.2500	140.6250	140.6250	4830429 B
'LINQ (Match - Lazy IEnumerable)'	100000	6,784,385.648 ns	135,159.5121 ns	290,945.1304 ns	7	250.0000	125.0000	125.0000	4830439 B
'Array (Match - Fallback)'	100000	6,812,793.701 ns	40,732.0373 ns	36,107.8901 ns	7	54.6875	54.6875	54.6875	1738653 B
'HashSet (Different Comparer)'	100000	7,497,254.730 ns	80,339.5419 ns	75,149.6574 ns	8	62.5000	62.5000	62.5000	1738753 B
'ImmutableHashSet (Mismatch - Same Count)'	100000	12,946,989.847 ns	94,279.9494 ns	83,576.7194 ns	9	-	-	-	-
'ImmutableHashSet (Match - Same Comparer)'	100000	13,615,905.022 ns	57,544.4439 ns	48,052.2169 ns	10	-	-	-	-

Performance Analysis Summary (100,000 Elements)

Case / Method	Before (ns)	After (ns)	Speedup Ratio	Memory Improvement
ImmutableHashSet (Larger Count)	9,477,300	2.328	~4,071,005x	Zero Alloc
ImmutableHashSet (Smaller Count)	4,733,200	2.300	~2,057,913x	Zero Alloc
HashSet (Smaller - Diff Comparer)	1,449,300	2.644	~548,146x	Zero Alloc
Array (Smaller Count)	647,900	2.711	~238,989x	Zero Alloc
BCL HashSet (Smaller Count)	313,800	2.595	~120,924x	Zero Alloc
HashSet (Different Comparer)	9,839,200	7,497,254	1.31x	Stable (~1.7 MB)
LINQ (Match/Mismatch)	11,341,500	6,406,188	1.77x	Stable (~4.8 MB)
BCL HashSet (Mismatch - Same Count)	8,636,300	5,640,651	1.53x	Zero Alloc
ImmutableHashSet (Match)	17,410,200	13,615,905	1.28x	Zero Alloc
ImmutableHashSet (Mismatch)	17,015,500	12,946,989	1.31x	Zero Alloc
List (Match/Diff - Fallback)	9,172,500	4,722,211	1.94x	Stable (~1.7 MB)
BCL HashSet (Match - Same Comp)	7,084,000	5,576,721	1.27x	Zero Alloc
List (Duplicates - Mismatch)	954,100	794,876	1.20x	Stable (~1.7 MB)
List (Duplicates - Match)	9,310,200	5,517,422	1.69x	Stable (~3.6 MB)
Array (Match - Fallback)	7,821,700	6,812,793	1.15x	Stable (~1.7 MB)

[eiriktsarpalis]

This change is adding a whole lot of runtime type checks. Is there tangible evidence (e.g. in the form of microbenchmarks) showing improvement here (both when other is a set but more importantly when it is not)?.

[aw0lid]

This change is adding a whole lot of runtime type checks. Is there tangible evidence (e.g. in the form of microbenchmarks) showing improvement here (both when other is a set but more importantly when it is not)?.

As the benchmark results indicate, there is no performance regression even in the fallback paths. This demonstrates that the added runtime type checks do not impact performance, while providing massive gains in the optimized paths

[eiriktsarpalis]

As the benchmark results indicate, there is no performance regression even in the fallback paths. This demonstrates that the added runtime type checks do not impact performance, while providing massive gains in the optimized paths

What do the numbers show when comparing small (0-10 elements) or collections that are not equal?

[aw0lid]

What do the numbers show when comparing small (0-10 elements) or collections that are not equal?

Performance Comparison: Before vs. After Optimization (10 elements)

Case / Method	Time (Before)	Time (After)	Speedup / Regression	Memory (Before)	Memory (After)	Memory Gain
ImmutableHashSet (Larger Count)	810.3 ns	2.29 ns	~353x Faster	440 B	0 B	-100%
ImmutableHashSet (Smaller Count)	408.5 ns	2.31 ns	~176x Faster	376 B	0 B	-100%
HashSet (Smaller - Diff Comp)	166.1 ns	2.57 ns	~64x Faster	336 B	0 B	-100%
BCL HashSet (Smaller Count)	164.0 ns	2.59 ns	~63x Faster	232 B	0 B	-100%
Array (Smaller Count)	166.1 ns	3.15 ns	~52x Faster	296 B	0 B	-100%
ImmutableHashSet (Mismatch)	857.6 ns	426.8 ns	~2.0x Faster	440 B	0 B	-100%
ImmutableHashSet (Match)	867.1 ns	456.5 ns	~1.9x Faster	440 B	0 B	-100%
List with Duplicates (Mismatch)	191.5 ns	184.4 ns	1.04x Faster	440 B	440 B	Stable
HashSet (Different Comparer)	315.6 ns	429.9 ns	1.36x Slower	336 B	336 B	Stable
BCL HashSet (Mismatch)	218.9 ns	461.7 ns	2.11x Slower	296 B	0 B	-100%
BCL HashSet (Match)	213.7 ns	468.5 ns	2.19x Slower	296 B	0 B	-100%
Array (Match - Fallback)	191.0 ns	552.1 ns	2.89x Slower	296 B	296 B	Stable
List (Match - Fallback)	235.2 ns	602.4 ns	2.56x Slower	336 B	336 B	Stable
List (Last Diff - Fallback)	221.1 ns	618.7 ns	2.80x Slower	336 B	336 B	Stable
List with Duplicates (Match)	315.5 ns	695.4 ns	2.20x Slower	528 B	528 B	Stable
LINQ (Mismatch/Match)	~470.0 ns	~800.0 ns	1.72x Slower	736 B	736 B	Stable

---

Based on the data, there is a minor increase in execution time for micro-collections (N=10) due to the necessary type-checks and comparer validation. In exchange, we achieved Zero Allocations for all Set-to-Set comparisons.

What do you think, is it a good trade-off ?

[aw0lid]

The count validation has been moved out of SetEqualsWithImmutableHashset and SetEqualsWithHashset, and the iteration logic in SetEqualsWithImmutableHashset has been reversed. This was done to make these methods reusable for optimizing other set operations, such as IsProperSubsetOf and IsSubsetOf, in subsequent PRs after this one is merged

This refactoring enables us to implement logic like the following:

privatestaticboolIsProperSubsetOf(IEnumerable<T>other,MutationInputorigin){Requires.NotNull(other,nameof(other));if(origin.Root.IsEmpty){returnother.Any();}if(otherisICollection<T>otherAsICollectionGeneric){// We check for < instead of != because other is not guaranteed to be a set, it could be a collection with duplicates.if(otherAsICollectionGeneric.Count<=origin.Count){returnfalse;}switch(other){caseImmutableHashSet<T>otherAsImmutableHashSet:if(origin.EqualityComparer.Equals(otherAsImmutableHashSet.KeyComparer)){returnSetEqualsWithImmutableHashset(otherAsImmutableHashSet,origin);}break;caseHashSet<T>otherAsHashset:if(origin.EqualityComparer.Equals(otherAsHashset.Comparer)){returnSetEqualsWithHashset(otherAsHashset,origin);}break;}}elseif(otherisICollectionotherAsICollection&&otherAsICollection.Count<=origin.Count){returnfalse;}varotherSet=newHashSet<T>(other,origin.EqualityComparer);if(otherSet.Count<=origin.Count){returnfalse;}returnSetEqualsWithHashset(otherSet,origin);}

[eiriktsarpalis]

Could you share updated benchmark numbers please?

[aw0lid]

Could you share updated benchmark numbers please?

I have already updated the PR description with the latest benchmark results. You can find the comparison and the performance improvements detailed there

[aw0lid]

CI seems to be stuck on infrastructure issues. Could someone please trigger a re-run for the failed checks? Thanks!

[eiriktsarpalis]

/ba-g test failures are unrelated