8000 Document Dictionary.{Remove,Clear} enumeration safety (#3451) · CAndRyan/dotnet-api-docs@509a629 · GitHub
[go: up one dir, main page]

Skip to content

Commit 509a629

Browse files
rojicarlossanlop
authored andcommitted
Document Dictionary.{Remove,Clear} enumeration safety (dotnet#3451)
1 parent b2dfc95 commit 509a629

File tree

5 files changed

+49
-17
lines changed

5 files changed

+49
-17
lines changed

xml/System.Collections.Generic/Dictionary`2+Enumerator.xml

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,9 @@
6565
6666
If <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> also return `false`. If the last call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> returned `false`, <xref:System.Collections.Generic.Dictionary%602.Enumerator.Current%2A> is undefined. You cannot set <xref:System.Collections.Generic.Dictionary%602.Enumerator.Current%2A> to the first element of the collection again; you must create a new enumerator instance instead.
6767
68-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
68+
An enumerator remains valid as long as the collection rema 8000 ins unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
69+
70+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
6971
7072
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization.
7173
@@ -216,7 +218,9 @@
216218
217219
If <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> also return `false`.
218220
219-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
221+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
222+
223+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
220224
221225
]]></format>
222226
</remarks>
@@ -496,7 +500,9 @@
496500
## Remarks
497501
After calling the <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> method, you must call the <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> method to advance the enumerator to the first element of the collection before reading the value of the <xref:System.Collections.Generic.Dictionary%602.Enumerator.Current%2A> property.
498502
499-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
503+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
504+
505+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
500506
501507
]]></format>
502508
</remarks>

xml/System.Collections.Generic/Dictionary`2+KeyCollection+Enumerator.xml

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,9 @@
6262
6363
If <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> also return `false`. If the last call to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> returned `false`, <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.Current%2A> is undefined. You cannot set <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.Current%2A> to the first element of the collection again; you must create a new enumerator instance instead.
6464
65-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
65+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
66+
67+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
6668
6769
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization.
6870
@@ -217,7 +219,9 @@
217219
218220
If <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> also return `false`.
219221
220-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
222+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
223+
224+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
221225
222226
]]></format>
223227
</remarks>
@@ -324,7 +328,9 @@
324328
## Remarks
325329
After calling the <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> method, you must call the <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> method to advance the enumerator to the first element of the collection before reading the value of the <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.Current%2A> property.
326330
327-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
331+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
332+
333+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
328334
329335
]]></format>
330336
</remarks>

xml/System.Collections.Generic/Dictionary`2+KeyCollection.xml

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -268,8 +268,10 @@
268268
269269
If <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> also return `false`. If the last call to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> returned `false`, <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.Current%2A> is undefined. You cannot set <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.Current%2A> to the first element of the collection again; you must create a new enumerator instance instead.
270270
271-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.KeyCollection.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
272-
271+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
272+
273+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
274+
273275
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization.
274276
275277
Default implementations of collections in <xref:System.Collections.Generic?displayProperty=nameWithType> are not synchronized.
@@ -569,7 +571,9 @@
569571
570572
If <xref:System.Collections.IEnumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.IEnumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.IEnumerator.MoveNext%2A> also return `false`. If the last call to <xref:System.Collections.IEnumerator.MoveNext%2A> returned `false`, <xref:System.Collections.Generic.IEnumerator%601.Current%2A> is undefined. You cannot set <xref:System.Collections.Generic.IEnumerator%601.Current%2A> to the first element of the collection again; you must create a new enumerator instance instead.
571573
572-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.IEnumerator.MoveNext%2A> or <xref:System.Collections.IEnumerator.Reset%2A> throws an <xref:System.InvalidOperationException>.
574+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
575+
576+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
573577
574578
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization.
575579
@@ -833,7 +837,9 @@ finally {
833837
834838
If <xref:System.Collections.IEnumerator.MoveNext%2A> passes the end of the collection, the enumerator is positioned after the last element in the collection and <xref:System.Collections.IEnumerator.MoveNext%2A> returns `false`. When the enumerator is at this position, subsequent calls to <xref:System.Collections.IEnumerator.MoveNext%2A> also return `false`. If the last call to <xref:System.Collections.IEnumerator.MoveNext%2A> returned `false`, <xref:System.Collections.IEnumerator.Current%2A> is undefined. To set <xref:System.Collections.IEnumerator.Current%2A> to the first element of the collection again, you can call <xref:System.Collections.IEnumerator.Reset%2A> followed by <xref:System.Collections.IEnumerator.MoveNext%2A>.
835839
836-
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying, or deleting elements, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.IEnumerator.MoveNext%2A> or <xref:System.Collections.IEnumerator.Reset%2A> throws an <xref:System.InvalidOperationException>.
840+
An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding elements or changing the capacity, the enumerator is irrecoverably invalidated and the next call to <xref:System.Collections.Generic.Dictionary%602.Enumerator.MoveNext%2A> or <xref:System.Collections.Generic.Dictionary%602.Enumerator.System%23Collections%23IEnumerator%23Reset%2A> throws an <xref:System.InvalidOperationException>.
841+
842+
.NET Core 3.0+ only: The only mutating methods which do not invalidate enumerators are <xref:System.Collections.Generic.Dictionary%602.Remove%2A> and <xref:System.Collections.Generic.Dictionary%602.Clear%2A>.
837843
838844
The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. To guarantee thread safety during enumeration, you can lock the collection during the entire enumeration. To allow the collection to be accessed by multiple threads for reading and writing, you must implement your own synchronization.
839845

0 commit comments

Comments
 (0)
0