From 457c641741dd9731ae82d24af4abb7d9a7b61160 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 9 Jun 2025 16:34:34 -0700 Subject: [PATCH 1/4] Updates to Exchange and CompareExchange --- xml/System.Threading/Interlocked.xml | 18 ++++++------------ 1 file changed, 6 insertions(+), 12 deletions(-) diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index 0b5a99cdae5..76b527dda7a 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -1341,22 +1341,21 @@ If `comparand` and the object in `location1` are equal by reference, then `value - The type to be used for , , and . This type must be a reference type. + The type to be used for , , and . The destination, whose value is compared by reference with and possibly replaced. This is a reference parameter ( in C#, in Visual Basic). The value that replaces the destination value if the comparison by reference results in equality. The value that is compared by reference to the value at . - Compares two instances of the specified reference type for reference equality and, if they are equal, replaces the first one, as an atomic operation. + Compares two instances of the specified type for reference equality and, if they're equal, replaces the first one, as an atomic operation. The original value in . method for the value types , , , , and , but there is no support for other value types. +If `comparand` and the value in `location1` are equal by reference, then `value` is stored in `location1`. Otherwise, no operation is performed. The comparison and the exchange are performed as an atomic operation. The return value of this method is the original value in `location1`, whether or not the exchange takes place. > [!NOTE] -> This method overload is preferable to the method overload, because the latter requires the destination object to be accessed late-bound. +> This method overload is preferable to the method overload, because the latter requires the destination object to be accessed late-bound. ]]> @@ -2371,19 +2370,14 @@ If `comparand` and the object in `location1` are equal by reference, then `value - The type to be used for and . This type must be a reference type. + The type to be used for and . The variable to set to the specified value. This is a reference parameter ( in C#, in Visual Basic). The value to which the parameter is set. Sets a variable of the specified type to a specified value and returns the original value, as an atomic operation. The original value of . method for the , , , , and value types, but there is no support for other value types. - -> [!NOTE] -> This method overload is preferable to the method overload, because the latter requires late-bound access to the destination object . +This method overload is preferable to the method overload, because the latter requires late-bound access to the destination object. ]]> The address of is a pointer. From 2606f883d4b4a70e96c1a6bdb1a9200440343fb4 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 9 Jun 2025 16:36:05 -0700 Subject: [PATCH 2/4] Update Interlocked.xml --- xml/System.Threading/Interlocked.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index 76b527dda7a..d8b2f716576 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -2373,7 +2373,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` The type to be used for and . The variable to set to the specified value. This is a reference parameter ( in C#, in Visual Basic). The value to which the parameter is set. - Sets a variable of the specified type to a specified value and returns the original value, as an atomic operation. + Sets a variable of the specified type to a specified value and returns the original value, as an atomic operation. The original value of . Date: Mon, 14 Jul 2025 18:04:26 -0700 Subject: [PATCH 3/4] respond to feedback --- xml/System.Threading/Interlocked.xml | 36 +++++++++------------------- 1 file changed, 11 insertions(+), 25 deletions(-) diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index d8b2f716576..be0461003f8 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -68,11 +68,9 @@ The and methods increment or decrement a variable and store the resulting value in a single operation. On most computers, incrementing a variable is not an atomic operation, requiring the following steps: -1. Load a value from an instance variable into a register. - -2. Increment or decrement the value. - -3. Store the value in the instance variable. +1. Load a value from an instance variable into a register. +2. Increment or decrement the value. +3. Store the value in the instance variable. If you do not use and , a thread can be preempted after executing the first two steps. Another thread can then execute all three steps. When the first thread resumes execution, it overwrites the value in the instance variable, and the effect of the increment or decrement performed by the second thread is lost. @@ -82,7 +80,6 @@ Ensure that any write or read access to a shared variable is atomic. Otherwise, the data might be corrupted or the loaded value might be incorrect. - ## Examples The following code example shows a thread-safe resource locking mechanism. @@ -611,8 +608,6 @@ ## Remarks If `comparand` and the value in `location1` are equal, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. - - ## Examples The following code example demonstrates a thread-safe method that accumulates a running total of values. Two threads add a series of values using the thread-safe method and ordinary addition, and when the threads complete the totals are compared. On a dual-processor computer, there is a significant difference in the totals. @@ -729,13 +724,11 @@ ## Remarks If `comparand` and the value in `location1` are equal, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. - - ## Examples The following code example demonstrates a thread-safe method that accumulates a running total. The initial value of the running total is saved, and then the method is used to exchange the newly computed total with the old total. If the return value is not equal to the saved value of the running total, then another thread has updated the total in the meantime. In that case, the attempt to update the running total must be repeated. > [!NOTE] -> The method, introduced in version 2.0 of the .NET Framework, provides a more convenient way to accumulate thread-safe running totals for integers. +> The method provides a more convenient way to accumulate thread-safe running totals for integers. :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/CompareExchange/source2.cs" id="Snippet1"::: :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked CompareExchange0/VB/source.vb" id="Snippet1"::: @@ -877,7 +870,7 @@ If `comparand` and the value in `location1` are equal, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of this method is the original value in `location1`, whether or not the exchange takes place. > [!NOTE] -> is a platform-specific type. +> is a platform-specific type. ]]> @@ -951,12 +944,12 @@ ## Remarks > [!IMPORTANT] -> Beginning with .NET Framework 2.0, the method overload provides a type-safe alternative for reference types. We recommend that you call it instead of this overload. +> The method overload provides a type-safe alternative. We recommend that you call it instead of this overload. If `comparand` and the object in `location1` are equal by reference, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. > [!NOTE] -> The objects are compared for reference equality rather than value equality. As a result, two boxed instances of the same value type (for example, the integer 3) always appear to be unequal and no operation is performed. Do not use this overload with value types. +> The objects are compared for reference equality rather than value equality. As a result, two boxed instances of the same value type (for example, the integer 3) always appear to be unequal and no operation is performed. Do not use this overload with value types. ]]> @@ -1354,13 +1347,10 @@ If `comparand` and the object in `location1` are equal by reference, then `value If `comparand` and the value in `location1` are equal by reference, then `value` is stored in `location1`. Otherwise, no operation is performed. The comparison and the exchange are performed as an atomic operation. The return value of this method is the original value in `location1`, whether or not the exchange takes place. -> [!NOTE] -> This method overload is preferable to the method overload, because the latter requires the destination object to be accessed late-bound. - ]]> The address of is a null pointer. - An unsupported is specified. + An unsupported is specified. On .NET 8 and earlier versions, must be a reference type. On .NET 9 and later versions, must be a reference, primitive, or enum type. @@ -2007,7 +1997,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` ## Remarks > [!IMPORTANT] -> Beginning with .NET Framework 2.0, the method overload provides a type-safe alternative for reference types. We recommend that you call it instead of this overload. +> The method overload provides a type-safe alternative. We recommend that you call it instead of this overload. ]]> @@ -2375,13 +2365,9 @@ If `comparand` and the value in `location1` are equal by reference, then `value` The value to which the parameter is set. Sets a variable of the specified type to a specified value and returns the original value, as an atomic operation. The original value of . - - method overload, because the latter requires late-bound access to the destination object. - ]]> - + To be added. The address of is a pointer. - An unsupported is specified. + An unsupported is specified. On .NET 8 and earlier versions, must be a reference type. On .NET 9 and later versions, must be a reference, primitive, or enum type. From 01e35da75235b3eb5c928c0ce554adfcff5a2700 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 21 Jul 2025 10:28:35 -0700 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Jan Kotas --- xml/System.Threading/Interlocked.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index be0461003f8..85fb1ee7f2d 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -944,7 +944,7 @@ ## Remarks > [!IMPORTANT] -> The method overload provides a type-safe alternative. We recommend that you call it instead of this overload. +> The method overload provides a generic alternative that can be used for concrete reference types. If `comparand` and the object in `location1` are equal by reference, then `value` is stored in `location1`. Otherwise, no operation is performed. The compare and exchange operations are performed as an atomic operation. The return value of is the original value in `location1`, whether or not the exchange takes place. @@ -1997,7 +1997,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` ## Remarks > [!IMPORTANT] -> The method overload provides a type-safe alternative. We recommend that you call it instead of this overload. +> The method overload provides a generic alternative that can be used for concrete reference types. ]]>