Repository navigation
Skip clearing reference-free Dictionary entries - #136605
Conversation
Retain bucket and count resets, and clear entry storage only when it contains managed references. Insertion initializes every reused entry. Cover repeated clears and refilling after removals, including default values returned by CollectionsMarshal.
|
Azure Pipelines: Successfully started running 3 pipeline(s). 13 pipeline(s) were filtered out due to trigger conditions. There may be pipelines that require an authorized user to comment /azp run to run. |
|
Tagging subscribers to this area: @dotnet/area-system-collections |
@dotnet-policy-service agree |
lilinus
left a comment
There was a problem hiding this comment.
FWIW, it looks like Remove also skips clearing key and values in this case.
There was a problem hiding this comment.
🔵 Needs a closer look
The change alters core BCL Dictionary.Clear() GC-reachability behavior whose correctness hinges on every insertion path fully reinitializing Entry fields, a broad-impact concern that warrants human confirmation despite source verification.
No open issues 🎉
What changed in this PR
This PR optimizes Dictionary<TKey, TValue>.Clear() by skipping the Array.Clear(_entries, ...) call when the entry type contains no managed references (!RuntimeHelpers.IsReferenceOrContainsReferences<Entry>()). For reference-free entries, clearing the backing array is unnecessary for GC correctness: resetting _buckets, _count, _freeList, and _freeCount already makes old entries unreachable, and every insertion path fully initializes hashCode, next, key, and value before an entry index is reused. For entry types that contain references (keys or values), the existing clear is preserved so the GC can reclaim them. This mirrors the established pattern in List<T>.Clear() (List.cs:323), yielding large reductions in Clear() time for blittable key/value types.
Changes:
- Guard the entry-array clear in
Dictionary.Clear()behindRuntimeHelpers.IsReferenceOrContainsReferences<Entry>(), keeping bucket/count resets unconditional. - Add a new theory test
Clear_AfterRemovingEntries_CanRefillto the sharedDictionary_Generic_Tests<TKey, TValue>base, exercising remove→clear→refill cycles and asserting defaults are returned viaCollectionsMarshal.GetValueRefOrAddDefault.
| File | Description |
|---|---|
src/libraries/System.Private.CoreLib/src/System/Collections/Generic/Dictionary.cs |
Conditionally skip Array.Clear(_entries) for reference-free entry types in Clear(), with an explanatory comment on why reuse remains safe. |
src/libraries/System.Collections/tests/Generic/Dictionary/Dictionary.Generic.Tests.cs |
Add Clear_AfterRemovingEntries_CanRefill regression test (runs for all instantiated key/value type pairs) and the System.Runtime.InteropServices using directive. |
I reviewed the change against the insertion paths (Dictionary.cs:605, 1030, and the other TryInsert variants), the free-list reset semantics, and the shared BCL convention in List<T>.Clear(). The optimization is correct and well-targeted, the test covers both value-type and reference-type instantiations (via the abstract base class) and specifically validates that GetValueRefOrAddDefault returns default after a clear-and-refill, and the new using directive is alphabetically ordered. I found no objective defects to comment on.
Review effort: Balanced
This PR uses the optimization pattern used in #136605. In `HashSet<T>.Clear`, call `Array.Clear` on the `_entries` field only when `RuntimeHelpers.IsReferenceOrContainsReferences<Entry>()` returns true.
For batches of 16 collections with 65,536 items each, mean `Clear()` time fell by 68.25-78.89% for `int` and 91.90-93.31% for a 64-byte value type in two BenchmarkDotNet comparisons. This follows #136605. `Clear()` now sets the count to zero and resets the buckets without clearing the entry array when neither keys nor values contain object references. `RemoveAt()` also skips clearing the unused last entry. New items overwrite old entries before use. Types that contain references, including structs, are still cleared. The optimization uses `#if NET`. Older `System.Text.Json` targets still clear the entries. ### Performance Selected `ClearBench<T>.ClearOnly` results for 16 collections per batch. Setup and validation are outside timing. Times are microseconds (`us`) per batch, shown as mean +/- sample standard deviation for each process. | Type | Items | Launch | Baseline us | Patched us | Mean time reduction | | --- | ---: | ---: | ---: | ---: | ---: | | `int/int` | 65,536 | 1 | 948.442 +/- 245.964 | 301.114 +/- 74.096 | 68.25% | | `int/int` | 65,536 | 2 | 1686.345 +/- 407.006 | 355.910 +/- 56.282 | 78.89% | | `int/Wide` | 65,536 | 1 | 3641.539 +/- 160.504 | 243.621 +/- 26.646 | 93.31% | | `int/Wide` | 65,536 | 2 | 3815.881 +/- 310.630 | 309.206 +/- 122.243 | 91.90% | BenchmarkDotNet `0.16.0-preview.2`, `InProcessEmitToolchain`, verified High process priority. Each version ran in two fresh processes. Clear-only used 10 warmups and 100 measurements. Clear-and-refill and removal used 8 warmups and 30 measurements targeting 500 ms each. Windows 11 Pro x64 (build 26200), Ryzen 9 5950X, Release `.NET 12.0.0-dev`. ReadyToRun and tiered compilation were disabled; concurrent workstation GC was enabled. Clear-only iterations were shorter than BenchmarkDotNet recommends, and some results had multiple timing clusters. All samples are included. These comparisons do not establish statistical significance. The `int/RefValue` Clear-only runs were slower at both sizes, with large variation. At 65,536 items, clear-and-refill means differed by less than 0.3%. ### Validation - Windows x64, Release CoreCLR: `System.Collections.Tests` built from `420ee500343` passed 33,975 tests. Tests ran on the isolated benchmark runtime image with the matching collection implementation. No failures. - Existing coverage: [`Ordering_AddInsertRemoveClear_ExpectedOrderResults`](https://github.com/tedd/dotnet-runtime/blob/420ee500343ea736ba8e2b405af532cdc56bb34a/src/libraries/System.Collections/tests/Generic/OrderedDictionary/OrderedDictionary.Tests.cs#L49) checks keys, values, and entry order after removal, insertion, clear, and refill with different values. - The added [`RemoveAt_DoesNotExposeRemovedEntries`](https://github.com/tedd/dotnet-runtime/blob/420ee500343ea736ba8e2b405af532cdc56bb34a/src/libraries/System.Collections/tests/Generic/OrderedDictionary/OrderedDictionary.Tests.cs#L106) checks collision lookups after removing and reusing the first, middle, or last position. It verifies every surviving value and that the removed key remains absent. - The added test also passed on the unchanged baseline. - Release test builds and `git diff --check` passed. - Older-target `System.Text.Json` builds were not run. <details> <summary>Full benchmark results and setup</summary> `Wide` contains eight `long` fields (64 bytes), compares all fields, and hashes the first. `RefValue` contains a `long` and an object reference. Input values are created once and reused. Benchmark baseline `8ac60f59b95`, with this PR's collection implementation applied for the patched runs. Only `System.Collections.dll` differs between the baseline and patched runtime images. Native runtime files are identical. Baseline/patched order was randomized with seed 136605. No outliers were removed. Clear-only uses one invocation per measurement and checks that all collections are empty afterward. `CycleBench<T>.ClearAndRefill` clears and refills one collection per invocation. Refill is timed; existing storage and input values are reused. Each case recorded at least 10 seconds of measured work. Cleanup checks the final count. `RemoveBench<T>.RemoveLastAndRefill` removes every item from the end, then refills the collection. Both steps are timed. Removal cases recorded 14.86 to 16.54 seconds of measured work per case in each process. Removal results, in microseconds per complete remove-and-refill cycle: | Type | Items | Launch | Baseline us | Patched us | Mean time reduction | | --- | ---: | ---: | ---: | ---: | ---: | | `int/int` | 1,024 | 1 | 18.497 +/- 0.084 | 18.310 +/- 0.280 | 1.01% | | `int/int` | 1,024 | 2 | 19.212 +/- 0.478 | 18.429 +/- 0.157 | 4.08% | | `int/Wide` | 1,024 | 1 | 19.370 +/- 0.095 | 17.904 +/- 0.090 | 7.57% | | `int/Wide` | 1,024 | 2 | 19.360 +/- 0.204 | 17.882 +/- 0.072 | 7.63% | | `int/RefValue` | 1,024 | 1 | 24.226 +/- 0.239 | 20.053 +/- 0.096 | 17.23% | | `int/RefValue` | 1,024 | 2 | 24.117 +/- 0.144 | 20.026 +/- 0.092 | 16.96% | | `int/int` | 65,536 | 1 | 1194.100 +/- 5.450 | 1210.096 +/- 5.100 | -1.34% | | `int/int` | 65,536 | 2 | 1222.484 +/- 40.068 | 1178.343 +/- 6.381 | 3.61% | | `int/Wide` | 65,536 | 1 | 1243.667 +/- 11.943 | 1167.879 +/- 4.245 | 6.09% | | `int/Wide` | 65,536 | 2 | 1226.321 +/- 10.061 | 1163.653 +/- 6.413 | 5.11% | | `int/RefValue` | 65,536 | 1 | 1641.321 +/- 146.067 | 1546.590 +/- 15.562 | 5.77% | | `int/RefValue` | 65,536 | 2 | 1531.816 +/- 11.114 | 1557.660 +/- 10.510 | -1.69% | Clear-only batches of sixteen collections, in microseconds. | Type | Items | Launch | Baseline us | Patched us | Mean time reduction | | --- | ---: | ---: | ---: | ---: | ---: | | `int/int` | 1,024 | 1 | 6.805 +/- 3.223 | 2.450 +/- 0.392 | 64.00% | | `int/int` | 1,024 | 2 | 12.536 +/- 7.416 | 6.152 +/- 2.675 | 50.93% | | `int/Wide` | 1,024 | 1 | 25.533 +/- 7.656 | 2.386 +/- 0.788 | 90.66% | | `int/Wide` | 1,024 | 2 | 30.526 +/- 13.904 | 5.344 +/- 2.560 | 82.49% | | `int/RefValue` | 1,024 | 1 | 16.465 +/- 10.988 | 126.165 +/- 172.910 | -666.26% | | `int/RefValue` | 1,024 | 2 | 18.306 +/- 14.663 | 36.254 +/- 30.971 | -98.04% | | `int/int` | 65,536 | 1 | 948.442 +/- 245.964 | 301.114 +/- 74.096 | 68.25% | | `int/int` | 65,536 | 2 | 1686.345 +/- 407.006 | 355.910 +/- 56.282 | 78.89% | | `int/Wide` | 65,536 | 1 | 3641.539 +/- 160.504 | 243.621 +/- 26.646 | 93.31% | | `int/Wide` | 65,536 | 2 | 3815.881 +/- 310.630 | 309.206 +/- 122.243 | 91.90% | | `int/RefValue` | 65,536 | 1 | 1915.965 +/- 243.876 | 3470.072 +/- 901.223 | -81.11% | | `int/RefValue` | 65,536 | 2 | 1977.722 +/- 273.707 | 3291.893 +/- 1997.883 | -66.45% | Sustained clear-and-refill cycles, in microseconds. | Type | Items | Launch | Baseline us | Patched us | Mean time reduction | | --- | ---: | ---: | ---: | ---: | ---: | | `int/int` | 1,024 | 1 | 15.378 +/- 2.337 | 12.290 +/- 0.141 | 20.08% | | `int/int` | 1,024 | 2 | 12.254 +/- 0.076 | 12.068 +/- 0.075 | 1.52% | | `int/Wide` | 1,024 | 1 | 14.738 +/- 2.676 | 11.692 +/- 0.053 | 20.67% | | `int/Wide` | 1,024 | 2 | 12.538 +/- 0.057 | 11.654 +/- 0.051 | 7.05% | | `int/RefValue` | 1,024 | 1 | 14.190 +/- 0.454 | 15.089 +/- 2.427 | -6.33% | | `int/RefValue` | 1,024 | 2 | 13.956 +/- 0.074 | 14.218 +/- 0.164 | -1.88% | | `int/int` | 65,536 | 1 | 937.282 +/- 117.856 | 782.885 +/- 3.020 | 16.47% | | `int/int` | 65,536 | 2 | 819.182 +/- 3.418 | 790.334 +/- 4.451 | 3.52% | | `int/Wide` | 65,536 | 1 | 1022.343 +/- 87.347 | 770.039 +/- 7.441 | 24.68% | | `int/Wide` | 65,536 | 2 | 1013.245 +/- 2.766 | 829.045 +/- 3.530 | 18.18% | | `int/RefValue` | 65,536 | 1 | 909.919 +/- 12.602 | 907.706 +/- 11.144 | 0.24% | | `int/RefValue` | 65,536 | 2 | 908.084 +/- 3.763 | 909.624 +/- 4.090 | -0.17% | Higher patched means in at least one process: `int/RefValue` at 1,024 items (Clear-only, up to 666.3%), `int/RefValue` at 65,536 items (Clear-only, up to 81.1%), `int/RefValue` at 1,024 items (clear-and-refill, up to 6.3%), `int/RefValue` at 65,536 items (clear-and-refill, up to 0.2%), `int/int` at 65,536 items (remove-last-and-refill, up to 1.3%), `int/RefValue` at 65,536 items (remove-last-and-refill, up to 1.7%). **Timed methods** ```csharp [Benchmark] public void ClearOnly() => fixture.Clear(); [Benchmark] public void ClearAndRefill() { fixture.Clear(); fixture.Fill(); } ``` ```csharp [Benchmark] public void RemoveLastAndRefill() { fixture.RemoveAll(); fixture.Fill(); } ``` </details> > [!NOTE] > The implementation, tests, and pull request description were prepared with OpenAI Codex (Fable). I used [Tedd.DotNetLab](https://tedd.no/Tedd.DotNetLab/) for the performance investigation. I have manually reviewed and checked everything.
For 65,536 entries with
intkeys, this patch reduces meanClear()time by 78.6% forintvalues and 96.5% for a 64-byte value type.Skip the entry-array clear when
RuntimeHelpers.IsReferenceOrContainsReferences<Entry>()is false. The check covers both keys and values, including references inside structs. In the inspected optimized x64 code, the JIT folds the check and removes the condition and entry-array clear for entries with no managed references.The bucket-array clear and count resets remain. They make old entries unreachable. Each insertion initializes every entry field before reuse, including the default value returned through
CollectionsMarshal.GetValueRefOrAddDefault. Entries that contain managed references retain the existing clear operation.Performance
Selected
ClearBench<TKey,TValue>.ClearOnlyresults follow. Each batch clears four populated dictionaries with 65,536 entries each; population and validation are outside timing.Widecontains eightlongfields.int/intint/WideWindows 11 x64, Ryzen 9 5950X, freshly built Release
.NET 12.0.0-dev, BenchmarkDotNet0.16.0-preview.2withInProcessEmitToolchain. ReadyToRun, tiered PGO, and concurrent workstation GC were enabled. Values are mean ± sample SD of ten process means per image, with 15 observations per case. Baseline6526253; patchedd5aa26b. Only CoreLib differs between the runtime images.Across 28 cases, nine supported an improvement and 19 were inconclusive. The
int/RefValueClear-only mean at 1,024 entries was 10.1% higher; its Bonferroni-adjusted paired bootstrap interval was 0.873–1.442, including no change (ratio 1).RefValuecontains an object reference and along. The measurements do not establish a slowdown in that case.Validation
Clear_AfterRemovingEntries_CanRefill: all 12 cases passed in both configurations, including repeated clears, removed entries, and default-valued by-reference insertion.GCStress=0xC.git diff --checkpassed.Note
The implementation, tests, and pull request description were prepared with OpenAI Codex (Sol). I used Tedd.DotNetLab for the performance investigation. I have manually reviewed and checked everything.