diff --git a/xml/System.Threading.Channels/UnboundedPrioritizedChannelOptions`1.xml b/xml/System.Threading.Channels/UnboundedPrioritizedChannelOptions`1.xml index 3d351bb7004..4894ac111a9 100644 --- a/xml/System.Threading.Channels/UnboundedPrioritizedChannelOptions`1.xml +++ b/xml/System.Threading.Channels/UnboundedPrioritizedChannelOptions`1.xml @@ -25,7 +25,7 @@ To be added. - Provides options that control the behavior of instances created by . + Provides options that control the behavior of instances created by . To be added. diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index b54d8e98476..4ee9e333bdf 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -5566,8 +5566,8 @@ An exception was thrown during - An of Task instances on which to wait. - A to observe while waiting for the tasks to complete. + A collection of tasks on which to wait. + A token to observe while waiting for the tasks to complete. Waits for all of the provided objects to complete execution unless the wait is cancelled. To be added. The argument is . diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index f4305e68509..08ef3b6ca38 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -63,35 +63,35 @@ Provides atomic operations for variables that are shared by multiple threads. - 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. - - 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. - - The method atomically adds an integer value to an integer variable and returns the new value of the variable. - - The method atomically exchanges the values of the specified variables. The method combines two operations: comparing two values and storing a third value in one of the variables, based on the outcome of the comparison. The compare and exchange operations are performed as an atomic operation. - - 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. - + 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. + + 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. + + The method atomically adds an integer value to an integer variable and returns the new value of the variable. + + The method atomically exchanges the values of the specified variables. The method combines two operations: comparing two values and storing a third value in one of the variables, based on the outcome of the comparison. The compare and exchange operations are performed as an atomic operation. + + 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. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Interlocked.Exchange Int32 Example/CPP/class1.cpp" id="Snippet1"::: :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Overview/class1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked.Exchange Int32 Example/VB/class1.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked.Exchange Int32 Example/VB/class1.vb" id="Snippet1"::: + ]]> This type is thread safe. @@ -165,11 +165,11 @@ Adds two 32-bit integers and replaces the first integer with the sum, as an atomic operation. The new value that was stored at by this operation. - and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. - + and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. + ]]> The address of is a null pointer. @@ -232,10 +232,10 @@ Adds two 64-bit integers and replaces the first integer with the sum, as an atomic operation. The new value that was stored at by this operation. - and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. + and `value` is 1, the result is ; if `value` is 2, the result is ( + 1); and so on. No exception is thrown. ]]> @@ -599,21 +599,21 @@ Compares two double-precision floating point numbers for equality and, if they are equal, replaces the first value, as an atomic operation. The original value in . - 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. - - In the thread-safe method, 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. - + 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. + + In the thread-safe method, 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. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/CompareExchange/source.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked CompareExchange Double/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked CompareExchange Double/vb/source.vb" id="Snippet1"::: + ]]> The address of is a null pointer. @@ -715,23 +715,23 @@ Compares two 32-bit signed integers for equality and, if they are equal, replaces the first value, as an atomic operation. The original value in . - 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. - + 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, introduced in version 2.0 of the .NET Framework, provides a more convenient way to accumulate thread-safe running totals for integers. + :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.Interlocked CompareExchange0/CPP/source.cpp" id="Snippet1"::: :::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"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked CompareExchange0/VB/source.vb" id="Snippet1"::: + ]]> The address of is a null pointer. @@ -792,11 +792,11 @@ Compares two 64-bit signed integers for equality and, if they are equal, replaces the first value, as an atomic operation. The original value in . - is the original value in `location1`, whether or not the exchange takes place. - + is the original value in `location1`, whether or not the exchange takes place. + ]]> The address of is a null pointer. @@ -861,14 +861,14 @@ Compares two platform-specific handles or pointers for equality and, if they are equal, replaces the first one, as an atomic operation. The original value in . - [!NOTE] -> is a platform-specific type. - +> is a platform-specific type. + ]]> The address of is a null pointer. @@ -939,18 +939,18 @@ Compares two objects for reference equality and, if they are equal, replaces the first object, as an atomic operation. The original value in . - [!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. -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. +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. + ]]> Managed Threading @@ -1054,21 +1054,21 @@ If `comparand` and the object in `location1` are equal by reference, then `value Compares two single-precision floating point numbers for equality and, if they are equal, replaces the first value, as an atomic operation. The original value in . - 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. - - In the thread-safe method, 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. - + 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. + + In the thread-safe method, 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. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/CompareExchange/source1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked CompareExchange Single/vb/source.vb" id="Snippet1"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.Interlocked CompareExchange Single/vb/source.vb" id="Snippet1"::: + ]]> The address of is a null pointer. @@ -1334,16 +1334,16 @@ If `comparand` and the object in `location1` are equal by reference, then `value Compares two instances of the specified reference type for reference equality and, if they are 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. - + method for the value types , , , , and , but there is no support for other value types. + > [!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. + ]]> The address of is a null pointer. @@ -1415,24 +1415,24 @@ If `comparand` and the object in `location1` are equal by reference, then `value Decrements a specified variable and stores the result, as an atomic operation. The value of the variable immediately after the decrement operation finished. - , `location` - 1 = . No exception is thrown. - - - -## Examples - The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 1,000 and decremented each time the random number generator returns a midpoint value. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. - + , `location` - 1 = . No exception is thrown. + + + +## Examples + The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 1,000 and decremented each time the random number generator returns a midpoint value. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Decrement/decrement1.cs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.decrement/vb/decrement1.vb" id="Snippet1"::: - - The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.decrement/vb/decrement1.vb" id="Snippet1"::: + + The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Decrement/decrement2.cs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.decrement/vb/decrement2.vb" id="Snippet2"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.decrement/vb/decrement2.vb" id="Snippet2"::: + ]]> The address of is a pointer. @@ -1491,11 +1491,11 @@ If `comparand` and the object in `location1` are equal by reference, then `value Decrements the specified variable and stores the result, as an atomic operation. The value of the variable immediately after the decrement operation finished. - , `location` - 1 = . No exception is thrown. - + , `location` - 1 = . No exception is thrown. + ]]> The address of is a pointer. @@ -1782,15 +1782,15 @@ If `comparand` and the object in `location1` are equal by reference, then `value Sets a 32-bit signed integer to a specified value and returns the original value, as an atomic operation. The original value of . - The address of is a pointer. @@ -1983,8 +1983,8 @@ If `comparand` and the object in `location1` are equal by reference, then `value Sets an object to a specified value and returns a reference to the original object, as an atomic operation. The original value of . - [!IMPORTANT] @@ -2350,13 +2350,13 @@ If `comparand` and the object in `location1` are equal by reference, then `value 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. - + 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. @@ -2428,24 +2428,24 @@ If `comparand` and the object in `location1` are equal by reference, then `value Increments a specified variable and stores the result, as an atomic operation. The value of the variable immediately after the increment operation finished. - , `location` + 1 = . No exception is thrown. - - - -## Examples - The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 0 and incremented each time the random number generator returns a midpoint value until it reaches 10,000. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. - + , `location` + 1 = . No exception is thrown. + + + +## Examples + The following example determines how many random numbers that range from 0 to 1,000 are required to generate 1,000 random numbers with a midpoint value. To keep track of the number of midpoint values, a variable, `midpointCount`, is set equal to 0 and incremented each time the random number generator returns a midpoint value until it reaches 10,000. Because three threads generate the random numbers, the method is called to ensure that multiple threads don't update `midpointCount` concurrently. Note that a lock is also used to protect the random number generator, and that a object is used to ensure that the `Main` method doesn't finish execution before the three threads. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Increment/increment3.cs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.increment2/vb/Increment3.vb" id="Snippet3"::: - - The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.increment2/vb/Increment3.vb" id="Snippet3"::: + + The following example is similar to the previous one, except that it uses the class instead of a thread procedure to generate 50,000 random midpoint integers. In this example, a lambda expression replaces the `GenerateNumbers` thread procedure, and the call to the method eliminates the need for the object. + :::code language="csharp" source="~/snippets/csharp/System.Threading/Interlocked/Increment/increment4.cs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.increment2/vb/Increment4.vb" id="Snippet4"::: - + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.interlocked.increment2/vb/Increment4.vb" id="Snippet4"::: + ]]> The address of is a pointer. @@ -2507,11 +2507,11 @@ If `comparand` and the object in `location1` are equal by reference, then `value Increments a specified variable and stores the result, as an atomic operation. The value of the variable immediately after the increment operation finished. - , `location` + 1 = . No exception is thrown. - + , `location` + 1 = . No exception is thrown. + ]]> The address of is a pointer. @@ -2650,13 +2650,13 @@ If `comparand` and the object in `location1` are equal by reference, then `value Synchronizes memory access as follows: The processor that executes the current thread cannot reorder instructions in such a way that memory accesses before the call to execute after memory accesses that follow the call to . - class in the .NET Framework 4.5 as a convenience; it's a wrapper for the method. - - For most purposes, the C# `lock` statement, the Visual Basic `SyncLock` statement, or the class provide easier ways to synchronize data. - + class in the .NET Framework 4.5 as a convenience; it's a wrapper for the method. + + For most purposes, the C# `lock` statement, the Visual Basic `SyncLock` statement, or the class provide easier ways to synchronize data. + ]]> @@ -2694,19 +2694,19 @@ If `comparand` and the object in `location1` are equal by reference, then `value Provides a process-wide memory barrier that ensures that reads and writes from any CPU cannot move across the barrier. - method as follows: - The normal memory barrier ensures that the reads and writes from the current CPU can't move across the barrier. The process-wide memory barrier ensures that any read or write from any CPU being used in the process can't move across the barrier. -- The normal memory barrier allows reasonable shared access if *every* thread accessing the data uses barriers. The process-wide memory barrier forces *other CPUs* to synchronize with process memory (for example, to flush write buffers and synchronize read buffers). This allows for non-interlocked operations on some threads and still have reasonable shared access. +- The normal memory barrier allows reasonable shared access if *every* thread accessing the data uses barriers. The process-wide memory barrier forces *other CPUs* to synchronize with process memory (for example, to flush write buffers and synchronize read buffers). This allows for non-interlocked operations on some threads and still have reasonable shared access. -- The normal memory barrier imposes very little overhead; normal interlocked operations probably cost fewer than a hundred cycles. The process-wide memory barrier is very expensive. It has to force every CPU in the process do to something, at a probable cost of thousands of cycles. +- The normal memory barrier imposes very little overhead; normal interlocked operations probably cost fewer than a hundred cycles. The process-wide memory barrier is very expensive. It has to force every CPU in the process do to something, at a probable cost of thousands of cycles. The `MemoryBarrierProcessWide` method also suffers from all the subtleties of lock-free programming. Nevertheless, this method can be extremely useful when you actually need to call it, which should be rare. -This method wraps a call to [FlushProcessWriteBuffers](/windows/win32/api/processthreadsapi/nf-processthreadsapi-flushprocesswritebuffers) on Windows and [sys_membarrier](https://lore.kernel.org/patchwork/patch/188708/) on Linux. +This method wraps a call to [FlushProcessWriteBuffers](/windows/win32/api/processthreadsapi/nf-processthreadsapi-flushprocesswritebuffers) on Windows and `sys_membarrier` on Linux. ]]> @@ -2927,11 +2927,11 @@ This method wraps a call to [FlushProcessWriteBuffers](/windows/win32/api/proces Returns a 64-bit value, loaded as an atomic operation. The loaded value. - method is unnecessary on 64-bit systems, because 64-bit read operations are already atomic. On 32-bit systems, 64-bit read operations are not atomic unless performed using . - + method is unnecessary on 64-bit systems, because 64-bit read operations are already atomic. On 32-bit systems, 64-bit read operations are not atomic unless performed using . + ]]> @@ -3025,9 +3025,9 @@ This method wraps a call to [FlushProcessWriteBuffers](/windows/win32/api/proces Defines a memory fence that blocks speculative execution past this point until pending reads and writes are complete. -