From 644da248a525d78c898db3112f11ad48082004a0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Sat, 23 May 2026 19:42:33 -0700 Subject: [PATCH 1/2] remove .net fw remarks --- xml/System.Threading.Tasks/Task.xml | 8 +- .../TaskCreationOptions.xml | 4 +- xml/System.Threading.Tasks/TaskFactory.xml | 43 ++- xml/System.Threading.Tasks/TaskFactory`1.xml | 2 +- xml/System.Threading.Tasks/TaskScheduler.xml | 17 +- xml/System.Threading.Tasks/Task`1.xml | 12 +- .../AbandonedMutexException.xml | 4 +- xml/System.Threading/ApartmentState.xml | 2 +- .../CancellationTokenSource.xml | 14 +- xml/System.Threading/CompressedStack.xml | 62 +---- xml/System.Threading/EventWaitHandle.xml | 27 +- xml/System.Threading/EventWaitHandleAcl.xml | 7 +- xml/System.Threading/ExecutionContext.xml | 21 +- xml/System.Threading/Interlocked.xml | 2 +- xml/System.Threading/ManualResetEvent.xml | 6 +- xml/System.Threading/ManualResetEventSlim.xml | 3 +- xml/System.Threading/Mutex.xml | 25 +- xml/System.Threading/MutexAcl.xml | 2 - xml/System.Threading/NativeOverlapped.xml | 30 +- xml/System.Threading/Overlapped.xml | 21 +- xml/System.Threading/ReaderWriterLock.xml | 4 +- xml/System.Threading/Semaphore.xml | 24 +- xml/System.Threading/SemaphoreAcl.xml | 6 +- xml/System.Threading/SpinWait.xml | 4 +- xml/System.Threading/Thread.xml | 260 +++--------------- xml/System.Threading/ThreadAbortException.xml | 3 +- xml/System.Threading/ThreadPool.xml | 32 +-- xml/System.Threading/Timer.xml | 1 - xml/System.Threading/WaitHandle.xml | 65 ++--- 29 files changed, 149 insertions(+), 562 deletions(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index f9de4241ce7..fb88a74972f 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3019,7 +3019,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However,there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> @@ -3073,7 +3073,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However, particularly if your app targets .NET Framework 4.5 or later, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However,there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> @@ -3134,7 +3134,7 @@ Task t Status: RanToCompletion, Result: 42 in calls to or in accesses to the property. On .NET Framework 4.0, any exceptions not observed by the time the task instance is garbage collected will be propagated on the finalizer thread, which crashes the process. On .NET Framework 4.5 and later the default behavior changed so unobserved exceptions are not rethrown from the Finalizer. .NET Core does not rethrow the exception on the Finalizer. For more information and an example, see [Exception Handling (Task Parallel Library)](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + Tasks that throw unhandled exceptions store the resulting exception and propagate it wrapped in a in calls to or in accesses to the property. Unobserved exceptions are not rethrown from the Finalizer. For more information and an example, see [Exception Handling (Task Parallel Library)](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). ]]> @@ -3198,7 +3198,7 @@ Task t Status: RanToCompletion, Result: 42 The most common use of this property is to create and start a new task in a single call to the method. > [!NOTE] -> Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. +> The method provides the easiest way to create a object with default configuration values. The following example uses the static property to make two calls to the method. The first populates an array with the names of files in the user's MyDocuments directory, while the second populates an array with the names of subdirectories of the user's MyDocuments directory. It then calls the method, which displays information about the number of files and directories in the two arrays after the first two tasks have completed execution. diff --git a/xml/System.Threading.Tasks/TaskCreationOptions.xml b/xml/System.Threading.Tasks/TaskCreationOptions.xml index d2f43368cdf..8ed792d07fa 100644 --- a/xml/System.Threading.Tasks/TaskCreationOptions.xml +++ b/xml/System.Threading.Tasks/TaskCreationOptions.xml @@ -392,9 +392,7 @@ 64 - Forces continuations added to the current task to be executed asynchronously. - - Note that the member is available in the enumeration starting with the .NET Framework 4.6. + Forces continuations added to the current task to be executed asynchronously. diff --git a/xml/System.Threading.Tasks/TaskFactory.xml b/xml/System.Threading.Tasks/TaskFactory.xml index 76cfca8eb79..8e8934badc3 100644 --- a/xml/System.Threading.Tasks/TaskFactory.xml +++ b/xml/System.Threading.Tasks/TaskFactory.xml @@ -74,7 +74,7 @@ - The class, which creates and objects. You can call the overloads of this method to create and execute a task that requires non-default arguments. > [!WARNING] - > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. + > The method provides the easiest way to create a task with default configuration values and start it immediately. - The class, which creates objects. @@ -83,7 +83,7 @@ - Create a task and start it immediately by calling the method. > [!WARNING] - > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. + > The method provides the easiest way to create a task with default configuration values and start it immediately. - Create a task that starts when any one of the tasks in an array has completed by calling the method. @@ -104,7 +104,7 @@ ]]> - All public and protected members of are thread-safe and may be used concurrently from multiple threads. + All public and protected members of are thread-safe and can be used concurrently from multiple threads. Task Parallel Library (TPL) Samples for parallel programming with .NET @@ -5567,7 +5567,8 @@ The NotOn\* and OnlyOn\* , method is the recommended way to launch a compute-bound task. Use the method only when you require fine-grained control for a long-running, compute-bound task. This includes scenarios in which you want to control the following: + +The method is the recommended way to launch a compute-bound task. Use the method only when you require fine-grained control for a long-running, compute-bound task. This includes scenarios in which you want to control the following: - Task creation options. Tasks created by the method by default are created with the option. To override this behavior, or to provide other options, call a overload. @@ -5632,9 +5633,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling is functionally equivalent to creating a task by using one of its constructors, and then calling the method to schedule the task for execution. - Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. - - +You can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ## Examples The following example uses the method to repeatedly invoke an delegate that generates a random number, interprets it as a Unicode code point, converts it to a UTF16-encoded code unit, and displays information about the resulting character or characters. @@ -5704,7 +5703,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling `StartNew` is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. @@ -5778,7 +5777,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -5860,7 +5859,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling is functionally equivalent to creating a using one of its constructors and then calling the method to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. @@ -5951,7 +5950,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. @@ -6044,7 +6043,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6115,7 +6114,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6208,7 +6207,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a Task using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see [Task.Run vs Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6289,7 +6288,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can call the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. @@ -6379,7 +6378,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6455,7 +6454,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method as a quick way to call with default parameters. Note, however, that there is a difference in behavior between the two methods regarding : by default does not allow child tasks started with the option to attach to the current instance, whereas does. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. @@ -6540,7 +6539,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6627,7 +6626,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6713,7 +6712,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6795,7 +6794,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> @@ -6899,7 +6898,7 @@ The NotOn\* and OnlyOn\* , ## Remarks Calling StartNew is functionally equivalent to creating a using one of its constructors and then calling to schedule it for execution. - Starting with the .NET Framework 4.5, you can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. +You can use the method with an object as a quick way to call with default parameters. For more information and code examples, see the entry [Task.Run vs. Task.Factory.StartNew](https://devblogs.microsoft.com/pfxteam/task-run-vs-task-factory-startnew/) in the Parallel Programming with .NET blog. ]]> diff --git a/xml/System.Threading.Tasks/TaskFactory`1.xml b/xml/System.Threading.Tasks/TaskFactory`1.xml index 4646bd9a937..210d6147556 100644 --- a/xml/System.Threading.Tasks/TaskFactory`1.xml +++ b/xml/System.Threading.Tasks/TaskFactory`1.xml @@ -91,7 +91,7 @@ - Create a task and start it immediately by calling the method. You can call the overloads of this method to create and execute a task that requires non-default arguments. > [!WARNING] - > Starting with .NET Framework 4.5, the method provides the easiest way to create a task with default configuration values and start it immediately. + > The method provides the easiest way to create a task with default configuration values and start it immediately. - Create a task that starts when any one of the tasks in an array has completed by calling the or method. diff --git a/xml/System.Threading.Tasks/TaskScheduler.xml b/xml/System.Threading.Tasks/TaskScheduler.xml index 32de593f341..7abfcd233c7 100644 --- a/xml/System.Threading.Tasks/TaskScheduler.xml +++ b/xml/System.Threading.Tasks/TaskScheduler.xml @@ -348,7 +348,7 @@ The following example creates a custom task scheduler that limits the number of implements this method in order to support integration with debuggers. This method will only be invoked by the .NET Framework when the debugger requests access to the data. The enumerable returned will be traversed by debugging utilities to access the tasks currently queued to this scheduler, enabling the debugger to provide a representation of this information in the user interface. + A class derived from implements this method in order to support integration with debuggers. This method will only be invoked when the debugger requests access to the data. The enumerable returned will be traversed by debugging utilities to access the tasks currently queued to this scheduler, enabling the debugger to provide a representation of this information in the user interface. It is important to note that, when this method is called, all other threads in the process will be frozen. Therefore, it's important to avoid synchronization with other threads that may lead to blocking. If synchronization is necessary, and you are unable to acquire the lock in this method, then you should throw an exception so that the debugger does not block. The following example shows one possible approach in C#: @@ -551,7 +551,7 @@ protected override IEnumerable GetScheduledTasks() A typical implementation would store the task in an internal data structure, which would be serviced by threads that would execute those tasks at some time in the future. - This method is only meant to be called by the .NET Framework and should not be called directly by the derived class. This is necessary for maintaining the consistency of the system. + This method is only meant to be called by the .NET runtime and should not be called directly by the derived class. This is necessary for maintaining the consistency of the system. ]]> @@ -685,7 +685,7 @@ protected override IEnumerable GetScheduledTasks() ## Remarks Scheduler implementations are provided with instances to be executed through either the method or the method. When the scheduler deems it appropriate to run the provided task, should be used to do so. TryExecuteTask handles all aspects of executing a task, including action invocation, exception handling, state management, and lifecycle control. - must only be used for tasks provided to this scheduler by the .NET Framework infrastructure. It should not be used to execute arbitrary tasks obtained through custom mechanisms. + must only be used for tasks provided to this scheduler by the .NET runtime. It should not be used to execute arbitrary tasks obtained through custom mechanisms. ]]> @@ -823,20 +823,11 @@ protected override IEnumerable GetScheduledTasks() This event provides a mechanism to prevent exception escalation policy (which, by default, terminates the process) from triggering. -To make it easier for developers to write asynchronous code based on tasks, unobserved exceptions raise the exception, but the process does not terminate by default. Instead, the exception is handled by the runtime after the event is raised, regardless of whether an event handler observes the exception. This behavior can be configured. You can use the [``](/dotnet/framework/configure-apps/file-schema/runtime/throwunobservedtaskexceptions-element) configuration element to terminate the process instead: - -```xml - - - - - -``` +To make it easier for developers to write asynchronous code based on tasks, unobserved exceptions raise the exception, but the process does not terminate by default. Instead, the exception is handled by the runtime after the event is raised, regardless of whether an event handler observes the exception. ]]> Task Parallel Library (TPL) - <ThrowUnobservedTaskExceptions> Element diff --git a/xml/System.Threading.Tasks/Task`1.xml b/xml/System.Threading.Tasks/Task`1.xml index b282141f7fd..44a261f7c4d 100644 --- a/xml/System.Threading.Tasks/Task`1.xml +++ b/xml/System.Threading.Tasks/Task`1.xml @@ -79,14 +79,14 @@ class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap) first introduced in .NET Framework 4. Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. + The class represents a single operation that returns a value and that usually executes asynchronously. objects are one of the central components of the [task-based asynchronous pattern](https://learn.microsoft.com/dotnet/standard/asynchronous-programming-patterns/task-based-asynchronous-pattern-tap). Because the work performed by a object typically executes asynchronously on a thread pool thread rather than synchronously on the main application thread, you can use the property, as well as the , , and properties, to determine the state of a task. Most commonly, a lambda expression is used to specify the work that the task is to perform. - instances may be created in a variety of ways. The most common approach, which is available starting with .NET Framework 4.5, is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: + instances can be created in a variety of ways. The most common approach is to call the static or method. These methods provide a simple way to start a task by using default values and without acquiring additional parameters. The following example uses the method to start a task that loops and then displays the number of loop iterations: :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/run1.cs" id="Snippet6"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/run1.vb" id="Snippet6"::: - An alternative, and the most common way to start a task in .NET Framework 4, is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. + An alternative approach is to call the static or method. The property returns a object, and the property returns a object. Overloads of their `StartNew` method let you pass arguments, define task creation options, and specify a task scheduler. The following example uses the method to start a task. It is functionally equivalent to the code in the previous example. :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/TaskTResult/Overview/startnew1.cs" id="Snippet7"::: :::code language="vb" source="~/snippets/visualbasic/System.Threading.Tasks/TaskTResult/Overview/startnew1.vb" id="Snippet7"::: @@ -95,9 +95,9 @@ The class also provides constructors that initialize the task but that do not schedule it for execution. For performance reasons, the and `Task.Factory.StartNew` methods are the preferred mechanisms for creating and scheduling computational tasks, but for scenarios where task creation and scheduling must be separated, the constructors may be used, and the task's method may then be used to schedule the task for execution at a later time. - Starting with desktop apps that target .NET Framework 4.6, the culture of the thread that creates and invokes a task becomes part of the thread's context. That is, regardless of the current culture of the thread on which the task executes, the current culture of the task is the culture of the calling thread. For apps that target versions of .NET Framework prior to .NET Framework 4.6, the culture of the task is the culture of the thread on which the task executes. For more information, see the "Culture and task-based asynchronous operations" section in the topic. Note that Store apps follow the Windows Runtime in setting and getting the default culture. +The culture of the thread that creates and invokes a task becomes part of the thread's context. That is, regardless of the current culture of the thread on which the task executes, the current culture of the task is the culture of the calling thread. -For operations that do not return a value, you use the class. Starting with C# 7.0, for a more lightweight task that is a value type rather than a reference type, use the structure. +For operations that do not return a value, you use the class. For a more lightweight task that's a value type rather than a reference type, use the structure. ]]> @@ -2402,7 +2402,7 @@ For operations that do not return a value, you use the method. > [!NOTE] -> Starting with .NET Framework 4.5, the method provides the easiest way to create a object with default configuration values. +> The method provides the easiest way to create a object with default configuration values. The following example uses the static property to make three calls to the method. The first starts a `Task` object, which executes a lambda expression that returns 1. The second starts a `Task` object, which executes a lambda expression that instantiates a new `Test` instance. The third starts a `Task` object, which enumerates the files in the C:\Users\Public\Pictures\Sample Pictures\ directory. (Note that successful execution of the example requires that the directory exist and that it contain files. diff --git a/xml/System.Threading/AbandonedMutexException.xml b/xml/System.Threading/AbandonedMutexException.xml index 0cf848aceb3..83ec3673a13 100644 --- a/xml/System.Threading/AbandonedMutexException.xml +++ b/xml/System.Threading/AbandonedMutexException.xml @@ -64,12 +64,10 @@ ## Remarks When a thread abandons a mutex, the exception is thrown in the next thread that acquires the mutex. The thread might acquire the mutex because it was already waiting on the mutex or because it enters the mutex at a later time. - An abandoned mutex indicates a serious programming error. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. Prior to version 2.0 of the .NET Framework, such problems were hard to discover because no exception was thrown if a wait completed as the result of an abandoned mutex. For more information, see the class. + An abandoned mutex indicates a serious programming error. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, provided that the integrity of the data structures can be verified. - - ## Examples The following code example executes a thread that abandons five mutexes, demonstrating their effects on the , , and methods. The value of the property is displayed for the call. diff --git a/xml/System.Threading/ApartmentState.xml b/xml/System.Threading/ApartmentState.xml index 47ea3956f3e..c880ce6ca64 100644 --- a/xml/System.Threading/ApartmentState.xml +++ b/xml/System.Threading/ApartmentState.xml @@ -48,7 +48,7 @@ property of the thread to one of the values of the enumeration. Because a given thread can only initialize a COM apartment once, you cannot change the apartment type after the first call to the unmanaged code. diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index 0fae0716354..dd9ffe37b3a 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -69,30 +69,24 @@ object, which provides a cancellation token through its property and sends a cancellation message by calling its or method. +.NET uses a unified model for cooperative cancellation of asynchronous or long-running synchronous operations that involves two objects: +- A object, which provides a cancellation token through its property and sends a cancellation message by calling its or method. - A object, which indicates whether cancellation is requested. - The general pattern for implementing the cooperative cancellation model is: +The general pattern for implementing the cooperative cancellation model is: - Instantiate a object, which manages and sends cancellation notification to the individual cancellation tokens. - - Pass the token returned by the property to each task or thread that listens for cancellation. - - Call the method from operations that receive the cancellation token. Provide a mechanism for each task or thread to respond to a cancellation request. Whether you choose to cancel an operation, and exactly how you do it, depends on your application logic. - - Call the method to provide notification of cancellation. This sets the property on every copy of the cancellation token to `true`. - - Call the method when you are finished with the object. For more information, see [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). > [!IMPORTANT] -> This type implements the interface. When you have finished using an instance of the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - +> This type implements the interface. When you have finished using an instance of the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`finally` block. To dispose of it indirectly, use a language construct such as `using` in C#. ## Examples The following example uses a random number generator to emulate a data collection application that reads 10 integral values from eleven different instruments. A value of zero indicates that the measurement has failed for one instrument, in which case the operation should be cancelled and no overall mean should be computed. diff --git a/xml/System.Threading/CompressedStack.xml b/xml/System.Threading/CompressedStack.xml index 53430ec032d..6af4370addb 100644 --- a/xml/System.Threading/CompressedStack.xml +++ b/xml/System.Threading/CompressedStack.xml @@ -55,18 +55,7 @@ Provides methods for setting and capturing the compressed stack on the current thread. This class cannot be inherited. - - and actions. For example, if a action is two stack frames up from the current frame and there are no other code access security annotations between there and the current frame, the compressed stack records only that information, without having to serialize the entire call stack. - - The class is used internally by the class. For example, the method captures the compressed stack for the current call stack, along with impersonation and culture information. The class is used in turn by the class to flow context across threads, for example when scheduling thread pool tasks. - - This class is not used in ordinary application programming. - - ]]> - + To be added. @@ -108,16 +97,7 @@ Captures the compressed stack from the current thread. A object. - - and actions, in a compressed format. For example, if a action is two stack frames up from the current frame and there are no other code access security annotations between there and the current frame, the compressed stack records only that information, without having to serialize the entire call stack. - - The captured compressed stack can be applied to another thread. - - ]]> - + To be added. @@ -159,14 +139,7 @@ Creates a copy of the current compressed stack. A object representing the current compressed stack. - - - + To be added. @@ -209,14 +182,7 @@ Gets the compressed stack for the current thread. A for the current thread. - - returns an empty object. - - ]]> - + To be added. A caller in the call chain does not have permission to access unmanaged code. -or- @@ -280,16 +246,7 @@ The object to be populated with serialization information. The structure representing the destination context of the serialization. Sets the object with the logical context information needed to recreate an instance of this execution context. - - sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. - - For more information, see . - - ]]> - + To be added. is . @@ -347,14 +304,7 @@ A that represents the method to be run in the specified security context. The object to be passed to the callback method. Runs a method in the specified compressed stack on the current thread. - - - + To be added. is . diff --git a/xml/System.Threading/EventWaitHandle.xml b/xml/System.Threading/EventWaitHandle.xml index cf8775cfee7..c87adf9a525 100644 --- a/xml/System.Threading/EventWaitHandle.xml +++ b/xml/System.Threading/EventWaitHandle.xml @@ -247,12 +247,7 @@ There was some other error. The `HResult` property might provide more informatio The is too long. Length restrictions might depend on the operating system or configuration. The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. - - The enum value was out of legal range. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + The enum value was out of legal range. Overview of synchronization primitives @@ -337,11 +332,7 @@ There was some other error. The `HResult` property might provide more informatio The named event exists and has access control security, but the user does not have . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. - The enum value was out of legal range. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + The enum value was out of legal range. Overview of synchronization primitives @@ -553,19 +544,13 @@ An object with the specified exists, but the specified Multiple calls to this method that use the same value for `name` do not necessarily return the same object, even though the objects that are returned represent the same named system event. - In .NET Framework, this method overload is equivalent to calling the [System.Threading.EventWaitHandle.OpenExisting(System.String,System.Security.AccessControl.EventWaitHandleRights)](/dotnet/api/system.threading.eventwaithandle.openexisting?view=netframework-4.8&preserve-view=true#System_Threading_EventWaitHandle_OpenExisting_System_String_System_Security_AccessControl_EventWaitHandleRights_) method overload and specifying and rights, combined by using the bitwise `OR` operation. - Specifying the flag allows a thread to wait on the named system event, and specifying the flag allows a thread to call the and methods. ]]> A synchronization object with the provided cannot be opened. It might not exist, or a synchronization object of a different type might have the same name. In some cases, this exception might be thrown for invalid names. - is an empty string. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is an empty string. is . @@ -855,11 +840,7 @@ The `name` can be prefixed with `Global\` or `Local\` to specify a namespace. Wh ]]> - is an empty string. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is an empty string. is . diff --git a/xml/System.Threading/EventWaitHandleAcl.xml b/xml/System.Threading/EventWaitHandleAcl.xml index 34be9ed38c5..3ad8b6e2d1d 100644 --- a/xml/System.Threading/EventWaitHandleAcl.xml +++ b/xml/System.Threading/EventWaitHandleAcl.xml @@ -98,11 +98,7 @@ ]]> - The enum value was out of legal range. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + The enum value was out of legal range. The enum value was out of legal range. In some cases is thrown instead. is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\\" and "Local\\" are case-sensitive. @@ -114,7 +110,6 @@ There was some other error. The `HResult` property may provide more information. The is too long. Length restrictions may depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. The named event exists, but the user does not have the desired security access. - .NET Framework only: The length is beyond MAX_PATH (260 characters). diff --git a/xml/System.Threading/ExecutionContext.xml b/xml/System.Threading/ExecutionContext.xml index 2ead610bb88..a73ec0fd34f 100644 --- a/xml/System.Threading/ExecutionContext.xml +++ b/xml/System.Threading/ExecutionContext.xml @@ -67,18 +67,10 @@ class provides a single container for all information relevant to a logical thread of execution. In .NET Framework, this includes security context, call context, and synchronization context. In .NET Core, the security context and call context are not supported, however, the impersonation context and culture would typically flow with the execution context. Also in .NET Core, the synchronization context does not flow with the execution context, whereas in .NET Framework it may in some cases. For more information, see [ExecutionContext vs SynchronizationContext](https://devblogs.microsoft.com/pfxteam/executioncontext-vs-synchronizationcontext/). + The class provides a single container for all information relevant to a logical thread of execution. It includes impersonation context and culture, but excludes security context, call context, and synchronization context. For more information, see [ExecutionContext vs SynchronizationContext](https://devblogs.microsoft.com/pfxteam/executioncontext-vs-synchronizationcontext/). The class provides the functionality for user code to capture and transfer this context across user-defined asynchronous points. The common language runtime ensures that the is consistently transferred across runtime-defined asynchronous points within the managed process. - - The following is applicable to .NET Framework only. - - - An execution context is the managed equivalent of a COM apartment. Within an application domain, the entire execution context must be transferred whenever a thread is transferred. This situation occurs during transfers made by the method, most thread pool operations, and Windows Forms thread marshaling through the Windows message pump. It does not occur in unsafe thread pool operations (such as the method), which do not transfer the compressed stack. Wherever the compressed stack flows, the managed principal, synchronization, locale, and user context also flow. The class provides the and methods to get the execution context and the method to set the execution context for the current thread. - - An that is associated with a thread cannot be set on another thread. Attempting to do so will result in an exception being thrown. To propagate the from one thread to another, make a copy of the . - - Internally, the stores all data that is associated with the . This allows the data to be propagated when the is copied and transferred. - ]]> @@ -296,16 +288,7 @@ The object to be populated with serialization information. The structure representing the destination context of the serialization. Sets the specified object with the logical context information needed to recreate an instance of the current execution context. - - sets a with the logical call context information. During deserialization, the execution context object is reconstituted from the transmitted over the stream. - - For more information, see . - - ]]> - + To be added. is . diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index bac05d9b03b..b3ff2d9d9d1 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -2485,7 +2485,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` class in the .NET Framework 4.5 as a convenience; it's a wrapper for the method. + This methodis 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. diff --git a/xml/System.Threading/ManualResetEvent.xml b/xml/System.Threading/ManualResetEvent.xml index 99acf18530a..3bb7876505c 100644 --- a/xml/System.Threading/ManualResetEvent.xml +++ b/xml/System.Threading/ManualResetEvent.xml @@ -62,14 +62,12 @@ `ManualResetEvent` can also be used with the `static` and methods. - Beginning with the .NET Framework version 2.0, derives from the class. A is functionally equivalent to an created with . + derives from the class. A is functionally equivalent to an created with . > [!NOTE] > Unlike the class, the class provides access to named system synchronization events. - Beginning with the .NET Framework version 4.0, the class is a lightweight alternative to . - - +The class is a lightweight alternative to . ## Examples The following example demonstrates how works. The example starts with a in the unsignaled state (that is, `false` is passed to the constructor). The example creates three threads, each of which blocks on the by calling its method. When the user presses the **Enter** key, the example calls the method, which releases all three threads. Contrast this with the behavior of the class, which releases threads one at a time, resetting automatically after each release. diff --git a/xml/System.Threading/ManualResetEventSlim.xml b/xml/System.Threading/ManualResetEventSlim.xml index 9221f4add25..f04e4526483 100644 --- a/xml/System.Threading/ManualResetEventSlim.xml +++ b/xml/System.Threading/ManualResetEventSlim.xml @@ -56,8 +56,7 @@ You can use this class for better performance than when wait times are expected to be very short, and when the event does not cross a process boundary. uses busy spinning for a short time while it waits for the event to become signaled. When wait times are short, spinning can be much less expensive than waiting by using wait handles. However, if the event does not become signaled within a certain period of time, resorts to a regular event handle wait. > [!NOTE] -> In .NET Core and .NET 5+, the default spin-waiting duration is short: on the order of 10s of microseconds, depending on platform and processor. If you expect wait times to be much longer than that, you can still use this class instead of (perhaps configured with less or no spin-waiting). However, the performance benefit would likely be only marginal. - +> The default spin-waiting duration is short (on the order of tens of microseconds), depending on platform and processor. If you expect wait times to be much longer than that, you can still use this class instead of (perhaps configured with less or no spin-waiting). However, the performance benefit would likely be only marginal. ## Examples The following example shows how to use a . diff --git a/xml/System.Threading/Mutex.xml b/xml/System.Threading/Mutex.xml index 33d6ac0e6f8..8a090e463e1 100644 --- a/xml/System.Threading/Mutex.xml +++ b/xml/System.Threading/Mutex.xml @@ -68,13 +68,13 @@ - The time-out interval specified in the call to a method that has a `millisecondsTimeout` or `timeout` parameter has elapsed. When this happens, the method returns `false`, and the calling thread makes no further attempt to acquire ownership of the mutex. In this case, you should structure your code so that access to the resource that is protected by the mutex is denied to the calling thread. Because the thread never acquired ownership of the mutex, it must not call the method. The second example in the Examples section illustrates this pattern. - The class enforces thread identity, so a mutex can be released only by the thread that acquired it. By contrast, the class does not enforce thread identity. A mutex can also be passed across application domain boundaries. + The class enforces thread identity, so a mutex can be released only by the thread that acquired it. By contrast, the class does not enforce thread identity. The thread that owns a mutex can request the same mutex in repeated calls to without blocking its execution. However, the thread must call the method the same number of times to release ownership of the mutex. Because the class inherits from , you can also call the static and methods to synchronize access to a protected resource. - If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the abandoned mutex. Before version 2.0 of the .NET Framework, no exception was thrown. + If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled, and the next waiting thread gets ownership. An is thrown in the next thread that acquires the abandoned mutex. > [!CAUTION] > An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. @@ -93,7 +93,6 @@ [!INCLUDE[backslash-mutex-note](~/includes/backslash-mutex.md)] - ## Examples This example shows how a local object is used to synchronize access to a protected resource. Because each calling thread is blocked until it acquires ownership of the mutex, it must call the method to release ownership of the mutex. @@ -335,8 +334,6 @@ There was some other error. The `HResult` property might provide more informatio Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions might depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. - - .NET Framework only: is longer than MAX_PATH (260 characters). Managed Threading Mutexes @@ -497,8 +494,6 @@ There was some other error. The `HResult` property might provide more informatio Windows only: specified an unknown namespace. See Object Names for more information. The is too long. Length restrictions might depend on the operating system or configuration. A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. - - .NET Framework only: is longer than MAX_PATH (260 characters). Managed Threading Mutexes @@ -726,11 +721,7 @@ An object with the specified exists, but the specified ]]> - is an empty string. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is an empty string. is . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. @@ -857,15 +848,13 @@ There was some other error. The `HResult` property might provide more informatio A thread that owns a mutex can specify the same mutex in repeated wait function calls without blocking its execution. The number of calls is kept by the common language runtime. The thread must call the same number of times to release ownership of the mutex. - If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled and the next waiting thread gets ownership. If no one owns the mutex, the state of the mutex is signaled. Beginning in version 2.0 of the .NET Framework, an is thrown in the next thread that acquires the mutex. Prior to version 2.0 of the .NET Framework, no exception was thrown. + If a thread terminates while owning a mutex, the mutex is said to be abandoned. The state of the mutex is set to signaled and the next waiting thread gets ownership. If no one owns the mutex, the state of the mutex is signaled. An is thrown in the next thread that acquires the mutex. > [!CAUTION] > An abandoned mutex often indicates a serious error in the code. When a thread exits without releasing the mutex, the data structures protected by the mutex might not be in a consistent state. The next thread to request ownership of the mutex can handle this exception and proceed, if the integrity of the data structures can be verified. In the case of a system-wide mutex, an abandoned mutex might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). - - ## Examples The following example shows how a local object is used to synchronize access to a protected resource. The thread that creates the mutex does not own it initially. The method is used to release the mutex when it is no longer needed. @@ -975,11 +964,7 @@ There was some other error. The `HResult` property might provide more informatio ]]> - is an empty string. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is an empty string. is . diff --git a/xml/System.Threading/MutexAcl.xml b/xml/System.Threading/MutexAcl.xml index 0ec9f47d14d..800cb1f5c18 100644 --- a/xml/System.Threading/MutexAcl.xml +++ b/xml/System.Threading/MutexAcl.xml @@ -95,8 +95,6 @@ ]]> - - .NET Framework only: is longer than MAX_PATH (260 characters). is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\\" and "Local\\" are case-sensitive. diff --git a/xml/System.Threading/NativeOverlapped.xml b/xml/System.Threading/NativeOverlapped.xml index 2a84830f730..97d0a9b4112 100644 --- a/xml/System.Threading/NativeOverlapped.xml +++ b/xml/System.Threading/NativeOverlapped.xml @@ -48,11 +48,11 @@ Provides an explicit layout that is visible from unmanaged code and that will have the same layout as the Win32 OVERLAPPED structure with additional reserved fields at the end. - .NET Framework value type represents an unmanaged version of the Win32 OVERLAPPED structure. The layout of this structure must be identical to OVERLAPPED. Four additional DWORDs are reserved at the end. - + value type represents an unmanaged version of the Win32 OVERLAPPED structure. The layout of this structure must be identical to OVERLAPPED. Four additional DWORDs are reserved at the end. + ]]> @@ -223,11 +223,11 @@ Specifies the high word of the byte offset at which to start the transfer. - @@ -272,11 +272,11 @@ Specifies a file position at which to start the transfer. - diff --git a/xml/System.Threading/Overlapped.xml b/xml/System.Threading/Overlapped.xml index 93906b52243..df5d6fd7301 100644 --- a/xml/System.Threading/Overlapped.xml +++ b/xml/System.Threading/Overlapped.xml @@ -628,7 +628,7 @@ The unmanaged pointer returned by this method can be passed to the operating system in overlapped I/O operations. The structure is fixed in physical memory until is called. > [!IMPORTANT] -> The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. +> The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. ]]> @@ -700,7 +700,7 @@ The buffer or buffers specified in `userData` must be the same as those passed to the unmanaged operating system function that performs the asynchronous I/O. > [!NOTE] -> The runtime pins the buffer or buffers specified in `userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. +> The runtime pins the buffer or buffers specified in `userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. ]]> @@ -855,19 +855,7 @@ An delegate that represents the callback method invoked when the asynchronous I/O operation completes. Packs the current instance into a structure specifying the delegate to invoke when the asynchronous I/O operation is complete. Does not propagate the calling stack. An unmanaged pointer to a structure. - - structure is fixed in physical memory until is called. - - The caller is responsible for pinning the buffer. If the application domain is unloaded, however, the handle to the pinned buffer is destroyed and the buffer is released, leaving the I/O operation to write to the freed address. For this reason, it is better to use the method overload, in which the runtime pins the buffer. - -> [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. - - ]]> - + To be added. The current has already been packed. @@ -937,9 +925,6 @@ The runtime pins the buffer or buffers specified in`userData` for the duration of the I/O operation. If the application domain is unloaded, the runtime keeps the memory pinned until the I/O operation completes. -> [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. The method does not propagate the calling stack. Malicious code might be able to exploit this to avoid permission checks. - ]]> The caller does not have the required permission. diff --git a/xml/System.Threading/ReaderWriterLock.xml b/xml/System.Threading/ReaderWriterLock.xml index ca3f207972c..1123684bf72 100644 --- a/xml/System.Threading/ReaderWriterLock.xml +++ b/xml/System.Threading/ReaderWriterLock.xml @@ -51,7 +51,7 @@ ## Remarks > [!IMPORTANT] -> The .NET Framework has two reader-writer locks, and . is recommended for all new development. is similar to , but it has simplified rules for recursion and for upgrading and downgrading lock state. avoids many cases of potential deadlock. In addition, the performance of is significantly better than . +> .NET provides two reader-writer locks, and . is recommended for all new development. is similar to , but it has simplified rules for recursion and for upgrading and downgrading lock state. avoids many cases of potential deadlock. In addition, the performance of is significantly better than . is used to synchronize access to a resource. At any given time, it allows either concurrent read access for multiple threads, or write access for a single thread. In a situation where a resource is changed infrequently, a `ReaderWriterLock` provides better throughput than a simple one-at-a-time lock, such as . @@ -82,8 +82,6 @@ With the exception of -1, negative time-out values are not allowed. If you specify a negative integer other than -1, a time-out value of zero is used instead. (That is, the method returns without waiting, if the lock cannot be acquired immediately.) If you specify a that represents a negative number of milliseconds other than -1, is thrown. - - ## Examples The following example demonstrates how to use a to protect a shared resource, an integer value named `resource`, that is read concurrently and written exclusively by multiple threads. Note that the is declared at the class level so that it is visible to all threads. diff --git a/xml/System.Threading/Semaphore.xml b/xml/System.Threading/Semaphore.xml index de86e475e63..e949596793e 100644 --- a/xml/System.Threading/Semaphore.xml +++ b/xml/System.Threading/Semaphore.xml @@ -249,11 +249,7 @@ ]]> - is greater than . - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is greater than . is less than 1. @@ -352,11 +348,7 @@ There was some other error. The `HResult` property might provide more informatio ]]> - is greater than . - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is greater than . is less than 1. @@ -623,11 +615,7 @@ An object with the specified exists, but the specified ]]> - is an empty string. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is an empty string. is . A synchronization object with the provided cannot be created. A synchronization object of a different type might have the same name. In some cases, this exception may be thrown for invalid names. @@ -962,11 +950,7 @@ There was some other error. The `HResult` property might provide more informatio ]]> - is an empty string. - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is an empty string. is . diff --git a/xml/System.Threading/SemaphoreAcl.xml b/xml/System.Threading/SemaphoreAcl.xml index 9bbff2ce868..8e322f0ebff 100644 --- a/xml/System.Threading/SemaphoreAcl.xml +++ b/xml/System.Threading/SemaphoreAcl.xml @@ -102,11 +102,7 @@ is not a positive number. - is greater than . - --or- - -.NET Framework only: is longer than MAX_PATH (260 characters). + is greater than . is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\\" and "Local\\" are case-sensitive. diff --git a/xml/System.Threading/SpinWait.xml b/xml/System.Threading/SpinWait.xml index ba7e90c0ae7..c4f340de50b 100644 --- a/xml/System.Threading/SpinWait.xml +++ b/xml/System.Threading/SpinWait.xml @@ -57,9 +57,7 @@ ## Remarks encapsulates common spinning logic. On single-processor machines, yields are always used instead of busy waits, and on computers with Intel processors employing Hyper-Threading technology, it helps to prevent hardware thread starvation. SpinWait encapsulates a good mixture of spinning and true yielding. - is a value type, which means that low-level code can utilize SpinWait without fear of unnecessary allocation overheads. SpinWait is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework, such as . For most purposes where spin waiting is required, however, the type should be preferred over the method. - - + is a value type, which means that low-level code can utilize SpinWait without fear of unnecessary allocation overheads. SpinWait is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by .NET, such as . For most purposes where spin waiting is required, however, the type should be preferred over the method. ## Examples The following example shows how to use a : diff --git a/xml/System.Threading/Thread.xml b/xml/System.Threading/Thread.xml index 85bcf04315f..969aab35bc9 100644 --- a/xml/System.Threading/Thread.xml +++ b/xml/System.Threading/Thread.xml @@ -253,9 +253,7 @@ A delegate that represents the methods to be invoked when this thread begins executing. - The maximum stack size, in bytes, to be used by the thread, or 0 to use the default maximum stack size specified in the header for the executable. - - Important For partially trusted code, is ignored if it is greater than the default stack size. No exception is thrown. + The maximum stack size, in bytes, to be used by the thread, or 0 to use the default maximum stack size specified in the header for the executable. Initializes a new instance of the class, specifying a delegate that allows an object to be passed to the thread when the thread is started and specifying the maximum stack size for the thread. constructor overload is the recommended stack size for threads. If a thread has memory problems, the most likely cause is programming error, such as infinite recursion. -> [!IMPORTANT] -> Beginning with the .NET Framework 4, only fully trusted code can set `maxStackSize` to a value that is greater than the default stack size (1 megabyte). If a larger value is specified for `maxStackSize` when code is running with partial trust, `maxStackSize` is ignored and the default stack size is used. No exception is thrown. Code at any trust level can set `maxStackSize` to a value that is less than the default stack size. - -> [!NOTE] -> If you are developing a fully trusted library that will be used by partially trusted code, and you need to start a thread that requires a large stack, you must assert full trust before creating the thread, or the default stack size will be used. Do not do this unless you fully control the code that runs on the thread. - If `maxStackSize` is less than the minimum stack size, the minimum stack size is used. If `maxStackSize` is not a multiple of the page size, it is rounded to the next larger multiple of the page size. -> [!NOTE] -> On versions of Microsoft Windows prior to Windows XP and Windows Server 2003, `maxStackSize` is ignored, and the stack size specified in the executable header is used. - - If you specify a very small stack size, you might need to disable stack-overflow probing. When the stack is severely constrained, the probing can itself cause a stack overflow. To disable stack overflow probing, add the following to your application configuration file in a .NET Framework app. - -```xml - - - - - -``` - ]]> @@ -330,9 +309,7 @@ A delegate that represents the methods to be invoked when this thread begins executing. - The maximum stack size, in bytes, to be used by the thread, or 0 to use the default maximum stack size specified in the header for the executable. - - Important For partially trusted code, is ignored if it is greater than the default stack size. No exception is thrown. + The maximum stack size, in bytes, to be used by the thread, or 0 to use the default maximum stack size specified in the header for the executable. Initializes a new instance of the class, specifying the maximum stack size for the thread. constructor overload is the recommended stack size for threads. If a thread has memory problems, the most likely cause is programming error, such as infinite recursion. -> [!IMPORTANT] -> Beginning with the .NET Framework 4, only fully trusted code can set `maxStackSize` to a value that is greater than the default stack size (1 megabyte). If a larger value is specified for `maxStackSize` when code is running with partial trust, `maxStackSize` is ignored and the default stack size is used. No exception is thrown. Code at any trust level can set `maxStackSize` to a value that is less than the default stack size. - -> [!NOTE] -> If you are developing a fully trusted library that will be used by partially trusted code, and you need to start a thread that requires a large stack, you must assert full trust before creating the thread, or the default stack size will be used. Do not do this unless you fully control the code that runs on the thread. - - If `maxStackSize` is less than the minimum stack size, the minimum stack size is used. If `maxStackSize` is not a multiple of the page size, it is rounded to the next larger multiple of the page size. For example, if you are using the .NET Framework version 2.0 on Windows Vista, 256KB (262,144 bytes) is the minimum stack size, and the page size is 64KB (65,536 bytes). - -> [!NOTE] -> On versions of Microsoft Windows prior to Windows XP and Windows Server 2003, `maxStackSize` is ignored, and the stack size specified in the executable header is used. - - If you specify a very small stack size, you might need to disable stack-overflow probing. When the stack is severely constrained, the probing can itself cause a stack overflow. To disable stack overflow probing, add the following to your application configuration file in a .NET Framework app. - -```xml - - - - - -``` + If `maxStackSize` is less than the minimum stack size, the minimum stack size is used. If `maxStackSize` is not a multiple of the page size, it is rounded to the next larger multiple of the page size. ]]> @@ -434,44 +392,8 @@ Raises a in the thread on which it is invoked, to begin the process of terminating the thread. Calling this method usually terminates the thread. - - at run time on .NET 5 and later and .NET Core. - - When this method is invoked on a thread, the system throws a in the thread to abort it. `ThreadAbortException` is a special exception that can be caught by application code, but is re-thrown at the end of the `catch` block unless is called. `ResetAbort` cancels the request to abort, and prevents the `ThreadAbortException` from terminating the thread. Unexecuted `finally` blocks are executed before the thread is aborted. - -> [!NOTE] -> When a thread calls `Abort` on itself, the effect is similar to throwing an exception; the happens immediately, and the result is predictable. However, if one thread calls `Abort` on another thread, the abort interrupts whatever code is running. There is also a chance that a static constructor could be aborted. In rare cases, this might prevent instances of that class from being created in that application domain. - - The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the `finally` blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To wait until a thread has aborted, you can call the method on the thread after calling the method, but there is no guarantee the wait will end. - -> [!NOTE] -> The thread that calls might block if the thread that is being aborted is in a protected region of code, such as a `catch` block, `finally` block, or constrained execution region. If the thread that calls holds a lock that the aborted thread requires, a deadlock can occur. - - If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. - - If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. - - If `Abort` is called on a managed thread while it is executing unmanaged code, a `ThreadAbortException` is not thrown until the thread returns to managed code. - - If two calls to `Abort` come at the same time, it is possible for one call to set the state information and the other call to execute the `Abort`. However, an application cannot detect this situation. - - After `Abort` is invoked on a thread, the state of the thread includes . After the thread has terminated as a result of a successful call to `Abort`, the state of the thread is changed to . With sufficient permissions, a thread that is the target of an `Abort` can cancel the abort using the `ResetAbort` method. For an example that demonstrates calling the `ResetAbort` method, see the `ThreadAbortException` class. - - ]]> - - .NET Core and .NET 5+ only: In all cases. - The caller does not have the required permission. - The thread that is being aborted is currently suspended. - - - - Threads and Threading - Using threads and threading - Destroying threads + To be added. + In all cases. @@ -523,51 +445,8 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ An object that contains application-specific information, such as state, which can be used by the thread being aborted. Raises a in the thread on which it is invoked, to begin the process of terminating the thread while also providing exception information about the thread termination. Calling this method usually terminates the thread. - - at run time on .NET 5 and later and .NET Core. - - When this method is invoked on a thread, the system throws a in the thread to abort it. `ThreadAbortException` is a special exception that can be caught by application code, but is re-thrown at the end of the `catch` block unless is called. `ResetAbort` cancels the request to abort, and prevents the `ThreadAbortException` from terminating the thread. Unexecuted `finally` blocks are executed before the thread is aborted. - -> [!NOTE] -> When a thread calls `Abort` on itself, the effect is similar to throwing an exception; the happens immediately, and the result is predictable. However, if one thread calls `Abort` on another thread, the abort interrupts whatever code is running. There is a chance that a static constructor could be aborted. In rare cases, this might prevent instances of that class from being created in that application domain. - - The thread is not guaranteed to abort immediately, or at all. This situation can occur if a thread does an unbounded amount of computation in the `finally` blocks that are called as part of the abort procedure, thereby indefinitely delaying the abort. To wait until a thread has aborted, you can call the method on the thread after calling the method, but there is no guarantee that the wait will end. - -> [!NOTE] -> The thread that calls might block if the thread that is being aborted is in a protected region of code, such as a `catch` block, `finally` block, or constrained execution region. If the thread that calls holds a lock that the aborted thread requires, a deadlock can occur. - - If `Abort` is called on a thread that has not been started, the thread will abort when is called. If `Abort` is called on a thread that is blocked or is sleeping, the thread is interrupted and then aborted. - - If `Abort` is called on a thread that has been suspended, a is thrown in the thread that called , and is added to the property of the thread being aborted. A is not thrown in the suspended thread until is called. - - If `Abort` is called on a managed thread while it is executing unmanaged code, a `ThreadAbortException` is not thrown until the thread returns to managed code. - - If two calls to `Abort` come at the same time, it is possible for one call to set the state information and the other call to execute the `Abort`. However, an application cannot detect this situation. - - After `Abort` is invoked on a thread, the state of the thread includes . After the thread has terminated as a result of a successful call to `Abort`, the state of the thread is changed to . With sufficient permissions, a thread that is the target of an `Abort` can cancel the abort using the `ResetAbort` method. For an example that demonstrates calling the `ResetAbort` method, see the `ThreadAbortException` class. - -## Examples - The following code example shows how to pass information to a thread that is being aborted. - - :::code language="csharp" source="~/snippets/csharp/System.Threading/Thread/Abort/source.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading/Thread/Abort/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System.Threading/Thread/Abort/source.vb" id="Snippet1"::: - - ]]> - - .NET Core and .NET 5+ only: In all cases. - The caller does not have the required permission. - The thread that is being aborted is currently suspended. - - - - Threads and Threading - Using threads and threading - Destroying threads + To be added. + In all cases. @@ -616,7 +495,7 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ ## Remarks > [!IMPORTANT] -> The .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). +> .NET provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). The slot is allocated on all threads. @@ -696,7 +575,7 @@ This method is obsolete. On .NET 5 and later versions, calling this method produ ## Remarks > [!IMPORTANT] -> .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). +> .NET provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data. @@ -840,12 +719,12 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR - Notifies a host that execution is about to enter a region of code in which the effects of a thread abort or unhandled exception might jeopardize other tasks in the application domain. + Notifies a host that execution is about to enter a region of code in which the effects of a thread abort or unhandled exception might jeopardize other tasks. , because there can be other tasks in the domain waiting for the same lock. If the current task is terminated, other tasks could be deadlocked. @@ -969,13 +848,12 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR object that is returned by this property, together with its associated objects, determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default culture is determined, and how users set culture information for their computers. + The object that is returned by this property, together with its associated objects, determine the default format for dates, times, numbers, currency values, the sorting order of text, casing conventions, and string comparisons. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads. See the property to learn how a thread's default culture is determined, and how users set culture information for their computers. > [!IMPORTANT] -> The property doesn't work reliably when used with any thread other than the current thread. In .NET Framework, reading the property is reliable, although setting it for a thread other than the current thread is not. On .NET Core, an is thrown if a thread attempts to read or write the property on a different thread. -> We recommend that you use the property to retrieve and set the current culture. +> The property doesn't work reliably when used with any thread other than the current thread. An is thrown if a thread attempts to read or write the property on a different thread. We recommend that you use the property to retrieve and set the current culture. - Beginning with the .NET Framework 4, you can set the property to a neutral culture. This is because the behavior of the class has changed: When it represents a neutral culture, its property values (in particular, the , , , , and properties) now reflect the specific culture that is associated with the neutral culture. In earlier versions of the .NET Framework, the property threw a exception when a neutral culture was assigned. +You can set the property to a neutral culture. When the class represents a neutral culture, its property values (in particular, the , , , , and properties) reflect the specific culture that's associated with the neutral culture. ## Examples The following example shows the threading statement that allows the user interface of a Windows Forms application to display in the culture that is set in Control Panel. Additional code is needed. @@ -987,7 +865,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR ]]> The property is set to . - .NET Core and .NET 5+ only: Reading or writing the culture of a thread from another thread is not supported. + Reading or writing the culture of a thread from another thread is not supported. @@ -1152,10 +1030,10 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads and application domains. See the property to learn how a thread's default UI culture is determined. + The UI culture specifies the resources an application needs to support user input and output, and by default is the same as the operating system culture. See the class to learn about culture names and identifiers, the differences between invariant, neutral, and specific cultures, and the way culture information affects threads. See the property to learn how a thread's default UI culture is determined. > [!IMPORTANT] -> The property doesn't work reliably when used with any thread other than the current thread. In .NET Framework, reading the property is reliable, although setting it for a thread other than the current thread is not. On .NET Core, an is thrown if a thread attempts to read or write the property on a different thread. +> The property doesn't work reliably when used with any thread other than the current thread. An is thrown if a thread attempts to read or write the property on a different thread. > We recommend that you use the property to retrieve and set the current culture. The returned by this property can be a neutral culture. Neutral cultures should not be used with formatting methods such as , , and . Use the method to get a specific culture, or use the property. @@ -1177,7 +1055,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR The property is set to . The property is set to a culture name that cannot be used to locate a resource file. Resource filenames must include only letters, numbers, hyphens or underscores. - .NET Core and .NET 5+ only: Reading or writing the culture of a thread from another thread is not supported. + Reading or writing the culture of a thread from another thread is not supported. @@ -1508,7 +1386,7 @@ You can specify the COM threading model for a C++ application using the [/CLRTHR ## Remarks > [!IMPORTANT] -> .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). +> .NET provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). After any thread calls `FreeNamedDataSlot`, any other thread that calls with the same name will allocate a new slot associated with the name. Subsequent calls to `GetNamedDataSlot` by any thread will return the new slot. However, any thread that still has a returned by an earlier call to `GetNamedDataSlot` can continue to use the old slot. @@ -1763,7 +1641,7 @@ The value is not guaranteed to be a zero-based processor number. ## Remarks > [!IMPORTANT] -> .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). +> .NET provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data. @@ -1836,18 +1714,7 @@ The value is not guaranteed to be a zero-based processor number. Returns the current domain in which the current thread is running. An representing the current application domain of the running thread. - - - + To be added. @@ -1890,18 +1757,7 @@ The value is not guaranteed to be a zero-based processor number. Returns a unique application domain identifier. A 32-bit signed integer uniquely identifying the application domain. - - - + To be added. @@ -2002,7 +1858,7 @@ The value is not guaranteed to be a zero-based processor number. ## Remarks > [!IMPORTANT] -> .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). +> .NET provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread expires. Data slots are unique per thread. No other thread (not even a child thread) can get that data. @@ -2643,13 +2499,10 @@ The value is not guaranteed to be a zero-based processor number. ## Remarks -In .NET Framework, this property is write-once, and because the default value of a thread's property is `null`, you can determine whether a name has already been explicitly assigned to the thread by comparing it with `null`. - The string assigned to the property can include any Unicode character. ]]> - .NET Framework only: A set operation was requested, but the property has already been set. @@ -2769,24 +2622,8 @@ The string assigned to the property can incl Cancels an requested for the current thread. - - . `ThreadAbortException` is a special exception that can be caught by application code, but is rethrown at the end of the catch block unless `ResetAbort` is called. `ResetAbort` cancels the request to abort, and prevents the `ThreadAbortException` from terminating the thread. - - See for an example that demonstrates calling the `ResetAbort` method. - - ]]> - - .NET Core and .NET 5+ only: In all cases. - - was not invoked on the current thread. - The caller does not have the required security permission for the current thread. - Destroying threads - + To be added. + In all cases. @@ -2842,21 +2679,8 @@ The string assigned to the property can incl Resumes a thread that has been suspended. - - [!CAUTION] -> Do not use the and methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. Deadlocks can occur very easily. - - ]]> - - .NET Core and .NET 5+ only: In all cases. - The thread has not been started, is dead, or is not in the suspended state. - The caller does not have the appropriate . - Pausing and interrupting threads - + To be added. + In all cases. @@ -2928,7 +2752,7 @@ The string assigned to the property can incl ]]> - .NET Core and .NET 5+ only: In all cases on macOS and Linux. + On macOS and Linux: In all cases. is not a valid apartment state. The thread has already been started. @@ -3059,7 +2883,7 @@ The string assigned to the property can incl ## Remarks > [!IMPORTANT] -> The .NET Framework provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). +> .NET provides two mechanisms for using thread local storage (TLS): thread-relative static fields (that is, fields that are marked with the attribute) and data slots. Thread-relative static fields provide much better performance than data slots, and enable compile-time type checking. For more information about using TLS, see [Thread Local Storage: Thread-Relative Static Fields and Data Slots](/dotnet/standard/threading/thread-local-storage-thread-relative-static-fields-and-data-slots). Threads use a local store memory mechanism to store thread-specific data. The common language runtime allocates a multi-slot data store array to each process when it is created. The thread can allocate a data slot in the data store, store and retrieve a data value in the slot, and free the slot for reuse after the thread procedure ends and the object has been reclaimed by garbage collection. Data slots are unique per thread. No other thread (not even a child thread) can get that data. @@ -3288,11 +3112,11 @@ The string assigned to the property can incl method is useful for implementing locks. Classes in the .NET Framework, such as and , use this method internally. essentially puts the processor into a very tight loop, with the loop count specified by the `iterations` parameter. The duration of the wait therefore depends on the speed of the processor. + The method is useful for implementing locks. Classes such as and use this method internally. essentially puts the processor into a very tight loop, with the loop count specified by the `iterations` parameter. The duration of the wait therefore depends on the speed of the processor. Contrast this with the method. A thread that calls yields the rest of its current slice of processor time, even if the specified interval is zero. Specifying a non-zero interval for removes the thread from consideration by the thread scheduler until the time interval has elapsed. - is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by the .NET Framework; for example, call or a statement that wraps (`lock` in C# or `SyncLock` in Visual Basic). + is not generally useful for ordinary applications. In most cases, you should use the synchronization classes provided by .NET; for example, call or a statement that wraps (`lock` in C# or `SyncLock` in Visual Basic). > [!CAUTION] > In the rare case where it is advantageous to avoid a context switch, such as when you know that a state change is imminent, make a call to the method in your loop. The code executes is designed to prevent problems that can occur on computers with multiple processors. For example, on computers with multiple Intel processors employing Hyper-Threading technology, prevents processor starvation in certain situations. @@ -3512,24 +3336,8 @@ The string assigned to the property can incl Either suspends the thread, or if the thread is already suspended, has no effect. - - [!CAUTION] -> Do not use the and methods to synchronize the activities of threads. You have no way of knowing what code a thread is executing when you suspend it. If you suspend a thread while it holds locks during a security permission evaluation, other threads in the might be blocked. If you suspend a thread while it is executing a class constructor, other threads in the that attempt to use that class are blocked. Deadlocks can occur very easily. - -When you call the `Suspend` method on a thread, the system notes that a thread suspension has been requested and allows the thread to execute until it reaches a safe point before actually suspending the thread. A safe point for a thread is a point in its execution at which garbage collection can be performed. Once a safe point is reached, the runtime guarantees that the suspended thread will not make any further progress in managed code. A thread executing outside managed code is always safe for garbage collection, and its execution continues until it attempts to resume execution of managed code. - - ]]> - - .NET Core and .NET 5+ only: In all cases. - The thread has not been started or is dead. - The caller does not have the appropriate . - Pausing and interrupting threads - + To be added. + In all cases. @@ -3657,7 +3465,7 @@ When you call the `Suspend` method on a thread, the system notes that a thread s ]]> - .NET Core and .NET 5+ only: In all cases on macOS and Linux. + On macOS and Linux: In all cases. is not a valid apartment state. The thread was started and has terminated, or the call is not being made from the thread's context while the thread is running. diff --git a/xml/System.Threading/ThreadAbortException.xml b/xml/System.Threading/ThreadAbortException.xml index 59524f627bf..aa950b0e2ff 100644 --- a/xml/System.Threading/ThreadAbortException.xml +++ b/xml/System.Threading/ThreadAbortException.xml @@ -55,10 +55,9 @@ method to destroy a thread, the common language runtime throws a on .NET Framework. is a special exception that can be caught, but it will automatically be raised again at the end of the `catch` block. When this exception is raised, the runtime executes all the `finally` blocks before ending the thread. Because the thread can do an unbounded computation in the `finally` blocks or call to cancel the abort, there is no guarantee that the thread will ever end. If you want to wait until the aborted thread has ended, you can call the method. is a blocking call that does not return until the thread actually stops executing. > [!NOTE] -> **.NET Core and .NET 5+ only:** Even though this type exists in .NET Core and .NET 5+, since is not supported, the common language runtime won't ever throw . +> Since is not supported, the common language runtime won't ever throw . > [!NOTE] > When the common language runtime (CLR) stops background threads after all foreground threads in a managed executable have ended, it does not use . Therefore, you cannot use to detect when background threads are being terminated by the CLR. diff --git a/xml/System.Threading/ThreadPool.xml b/xml/System.Threading/ThreadPool.xml index 372f705847a..f33c462eb4d 100644 --- a/xml/System.Threading/ThreadPool.xml +++ b/xml/System.Threading/ThreadPool.xml @@ -86,12 +86,12 @@ Timer-queue timers and registered wait operations also use the thread pool. Their callback functions are queued to the thread pool. - There is one thread pool per process. Beginning with the .NET Framework 4, the default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. The number of threads in the thread pool can be changed by using the method. Each thread uses the default stack size and runs at the default priority. + There is one thread pool per process. The default size of the thread pool for a process depends on several factors, such as the size of the virtual address space. A process can call the method to determine the number of threads. The number of threads in the thread pool can be changed by using the method. Each thread uses the default stack size and runs at the default priority. > [!NOTE] -> Unmanaged code that hosts the .NET Framework can change the size of the thread pool by using the `CorSetMaxThreads` function, defined in the mscoree.h file. +> Unmanaged code that hosts .NET can change the size of the thread pool by using the `CorSetMaxThreads` function, defined in the mscoree.h file. - The thread pool provides new worker threads or I/O completion threads on demand until it reaches the maximum for each category. When a maximum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. Beginning with the .NET Framework 4, the thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. + The thread pool provides new worker threads or I/O completion threads on demand until it reaches the maximum for each category. When a maximum is reached, the thread pool can create additional threads in that category or wait until some tasks complete. The thread pool creates and destroys worker threads in order to optimize throughput, which is defined as the number of tasks that complete per unit of time. Too few threads might not make optimal use of available resources, whereas too many threads could increase resource contention. > [!NOTE] > When demand is low, the actual number of thread pool threads can fall below the minimum values. @@ -101,8 +101,6 @@ > [!CAUTION] > You can use the method to increase the minimum number of threads. However, unnecessarily increasing these values can cause performance problems. If too many tasks start at the same time, all of them might appear to be slow. In most cases the thread pool will perform better with its own algorithm for allocating threads. - - ## Examples In the following example, the main application thread queues a method named `ThreadProc` to execute on a thread pool thread, sleeps for one second, and then exits. The `ThreadProc` method simply displays a message. @@ -491,13 +489,11 @@ If a thread pool implementation may have different types of work items, the coun [!NOTE] > When demand is low, the actual number of thread pool threads can fall below the minimum values. - - ## Examples The following example sets the minimum number of worker threads to four, and preserves the original value for the minimum number of asynchronous I/O completion threads. @@ -1292,7 +1288,7 @@ The following example uses the class, the structure, and the `OVERLAPPED` structure in the Win32 Platform SDK. -> [!CAUTION] -> Using the method could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread does not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - ]]> @@ -1543,9 +1536,6 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. -> [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - ]]> The caller does not have the required permission. @@ -1694,9 +1684,6 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. -> [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. @@ -1780,9 +1767,6 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. -> [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. @@ -1866,9 +1850,6 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. -> [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. @@ -1957,9 +1938,6 @@ The thread pool will invoke the work item's method, does not propagate the calling stack to the worker thread. This allows code to lose the calling stack and thereby to elevate its security privileges. -> [!CAUTION] -> Using could inadvertently open up a security hole. Code access security bases its permission checks on the permissions of all the callers on the stack. When work is queued on a thread pool thread using , the stack of the thread pool thread will not have the context of the actual callers. Malicious code might be able exploit this to avoid permission checks. - Using a for `waitObject` does not provide mutual exclusion for the callbacks because the underlying Windows API uses the default `WT_EXECUTEDEFAULT` flag, so each callback is dispatched on a separate thread pool thread. When you are finished using the that is returned by this method, call its method to release references to the wait handle. We recommend that you always call the method, even if you specify `true` for `executeOnlyOnce`. Garbage collection works more efficiently if you call the method instead of depending on the registered wait handle's finalizer. diff --git a/xml/System.Threading/Timer.xml b/xml/System.Threading/Timer.xml index 007b5ca90ef..ac9978bcd86 100644 --- a/xml/System.Threading/Timer.xml +++ b/xml/System.Threading/Timer.xml @@ -115,7 +115,6 @@ The timer delegate is specified when the timer is constructed and cannot be chan > - , which fires an event and executes the code in one or more event sinks at regular intervals. The class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. > - , which executes a single callback method on a thread pool thread at regular intervals. The callback method is defined when the timer is instantiated and cannot be changed. Like the class, this class is intended for use as a server-based or service component in a multithreaded environment; it has no user interface and is not visible at runtime. > - , a Windows Forms component that fires an event and executes the code in one or more event sinks at regular intervals. The component has no user interface and is designed for use in a single-threaded environment; it executes on the UI thread. -> - (.NET Framework only), an ASP.NET component that performs asynchronous or synchronous web page postbacks at a regular interval. > - , a timer that's integrated into the `Dispatcher` queue. This timer is processed with a specified priority at a specified time interval. When you create a timer, you can specify an amount of time to wait before the first execution of the method (due time), and an amount of time to wait between subsequent executions (period). The class has the same resolution as the system clock. This means that if the period is less than the resolution of the system clock, the delegate will execute at intervals defined by the resolution of the system clock, which is approximately 15 milliseconds on Windows 7 and Windows 8 systems. You can change the due time and period, or disable the timer, by using the method. diff --git a/xml/System.Threading/WaitHandle.xml b/xml/System.Threading/WaitHandle.xml index ac98ab83701..b0ac5db5583 100644 --- a/xml/System.Threading/WaitHandle.xml +++ b/xml/System.Threading/WaitHandle.xml @@ -74,33 +74,25 @@ The class itself is abstract. Classes derived from define a signaling mechanism to indicate taking or releasing access to a shared resource, but they use the inherited methods to block while waiting for access to shared resources. The classes derived from include: - The class. See [Mutexes](/dotnet/standard/threading/mutexes). - - The class and its derived classes, and . - - The class. See [Semaphore and SemaphoreSlim](/dotnet/standard/threading/semaphore-and-semaphoreslim). Threads can block on an individual wait handle by calling the instance method , which is inherited by classes derived from . The derived classes of differ in their thread affinity. Event wait handles (, , and ) and semaphores do not have thread affinity; any thread can signal an event wait handle or semaphore. Mutexes, on the other hand, do have thread affinity; the thread that owns a mutex must release it, and an exception is thrown if a thread calls the method on a mutex that it does not own. - Because the class derives from , these classes can be used to synchronize the activities of threads across application domain boundaries. - In addition to its derived classes, the class has a number of static methods that block a thread until one or more synchronization objects receive a signal. These include: -- , which allows a thread to signal one wait handle and immediately wait on another. - -- , which allows a thread to wait until all the wait handles in an array receive a signal. - -- , which allows a thread to wait until any one of a specified set of wait handles has been signaled. +- , which allows a thread to signal one wait handle and immediately wait on another. +- , which allows a thread to wait until all the wait handles in an array receive a signal. +- , which allows a thread to wait until any one of a specified set of wait handles has been signaled. The overloads of these methods provide timeout intervals for abandoning the wait, and the opportunity to exit a synchronization context before entering the wait, allowing other threads to use the synchronization context. > [!IMPORTANT] -> This type implements the interface. When you have finished using the type or a type derived from it, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the interface topic. - - implements the pattern. See [Implementing a Dispose method](/dotnet/standard/garbage-collection/implementing-dispose). When you derive from , use the property to store your native operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. - - +> This type implements the interface. When you have finished using the type or a type derived from it, you should dispose of it either directly or indirectly. To dispose of the type directly, call its method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` in C#. +> +> When you derive from , use the property to store your native operating system handle. You do not need to override the protected method unless you use additional unmanaged resources. ## Examples The following code example shows how two threads can do background tasks while the Main thread waits for the tasks to complete using the static and methods of the class. @@ -406,7 +398,7 @@ ## Remarks Assigning a new value to the property does not close the previous handle. This can result in a leaked handle. - Do not use this property in the .NET Framework version 2.0 or later; use the property instead. Setting this property to a valid handle also sets the property, but setting it to can result in a leaked handle. +Use the property instead. Setting this property to a valid handle also sets the property, but setting it to can result in a leaked handle. ]]> @@ -827,7 +819,7 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + is thrown when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. The method returns when all the handles are signaled. If more than 64 handles are passed, a is thrown. If the array contains duplicates, the call fails with a . @@ -836,8 +828,6 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. - - ## Examples The following code example shows how to use the thread pool to asynchronously create and write to a group of files. Each write operation is queued as a work item and signals when it is finished. The main thread waits for all the items to signal and then exits. @@ -846,21 +836,21 @@ If `millisecondsTimeout` is zero, the method does not block. It tests the state ]]> - The parameter is . -or- + The parameter is . + +-or- One or more of the objects in the array are . -or- - is an array with no elements and the .NET Framework version is 2.0 or later. + is an array with no elements. The array contains elements that are duplicates. The number of objects in is greater than the system permits. -or- The current thread is in state, and contains more than one element. - - is an array with no elements and the .NET Framework version is 1.0 or 1.1. The wait terminated because a thread exited without releasing a mutex. The array contains a transparent proxy for a in another application domain. @@ -1116,15 +1106,13 @@ The method returns when the wait ter -or- - is an array with no elements and the .NET Framework version is 2.0 or later. + is an array with no elements. The array contains elements that are duplicates. The number of objects in is greater than the system permits. -or- The current thread is in state, and contains more than one element. - - is an array with no elements and the .NET Framework version is 1.0 or 1.1. is a negative number other than -1, which represents an infinite time-out. The wait completed because a thread exited without releasing a mutex. @@ -1214,15 +1202,13 @@ The maximum value for `timeout` is is an array with no elements and the .NET Framework version is 2.0 or later. + is an array with no elements. The array contains elements that are duplicates. The number of objects in is greater than the system permits. -or- The attribute is applied to the thread procedure for the current thread, and contains more than one element. - - is an array with no elements and the .NET Framework version is 1.0 or 1.1. is a negative number other than -1 milliseconds, which represents an infinite time-out. @@ -1294,21 +1280,16 @@ The maximum value for `timeout` is is new in the .NET Framework version 2.0. In previous versions, the method returns `true` if the wait completes because a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + is thrown when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. The method throws an only when the wait completes because of an abandoned mutex. If `waitHandles` contains a released mutex with a lower index number than the abandoned mutex, the method completes normally and the exception is not thrown. -> [!NOTE] -> In versions of the .NET Framework earlier than version 2.0, if a thread exits or aborts without explicitly releasing a , and that `Mutex` is at index 0 (zero) in a `WaitAny` array on another thread, the index returned by `WaitAny` is 128 instead of 0. - This method returns when any handle is signaled. If more than one object becomes signaled during the call, the return value is the array index of the signaled object with the smallest index value of all the signaled objects. The maximum number of the wait handles is 64, and 63 if the current thread is in state. Calling this method overload is equivalent to calling the method overload and specifying -1 (or ) for `millisecondsTimeout` and `true` for `exitContext`. - - ## Examples The following code example demonstrates calling the method. @@ -1323,11 +1304,9 @@ The maximum value for `timeout` is array is . The number of objects in is greater than the system permits. - - is an array with no elements, and the .NET Framework version is 1.0 or 1.1. The wait completed because a thread exited without releasing a mutex. - is an array with no elements, and the .NET Framework version is 2.0 or later. + is an array with no elements. The array contains a transparent proxy for a in another application domain. @@ -1564,13 +1543,11 @@ The maximum number of the wait handles is 64, and 63 if the current thread is in One or more of the objects in the array is . The number of objects in is greater than the system permits. - - is an array with no elements, and the .NET Framework version is 1.0 or 1.1. is a negative number other than -1, which represents an infinite time-out. The wait completed because a thread exited without releasing a mutex. - is an array with no elements, and the .NET Framework version is 2.0 or later. + is an array with no elements. The array contains a transparent proxy for a in another application domain. @@ -1653,8 +1630,6 @@ The maximum value for `timeout` is array is . The number of objects in is greater than the system permits. - - is an array with no elements, and the .NET Framework version is 1.0 or 1.1. is a negative number other than -1 milliseconds, which represents an infinite time-out. @@ -1663,7 +1638,7 @@ The maximum value for `timeout` is is greater than Int32.MaxValue. The wait completed because a thread exited without releasing a mutex. - is an array with no elements, and the .NET Framework version is 2.0 or later. + is an array with no elements. The array contains a transparent proxy for a in another application domain. @@ -1726,7 +1701,7 @@ The maximum value for `timeout` is is new in the .NET Framework version 2.0. In previous versions, the method returns `true` when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. + is thrown when a mutex is abandoned. An abandoned mutex often indicates a serious coding error. In the case of a system-wide mutex, it might indicate that an application has been terminated abruptly (for example, by using Windows Task Manager). The exception contains information useful for debugging. The caller of this method blocks indefinitely until the current instance receives a signal. Use this method to block until a receives a signal from another thread, such as is generated when an asynchronous operation completes. For more information, see the interface. @@ -1734,8 +1709,6 @@ The maximum value for `timeout` is Date: Wed, 27 May 2026 15:02:36 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- xml/System.Threading.Tasks/Task.xml | 4 ++-- xml/System.Threading/Interlocked.xml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index fb88a74972f..d370d2fe4ce 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3019,7 +3019,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However,there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> @@ -3073,7 +3073,7 @@ Task t Status: RanToCompletion, Result: 42 class implements the interface because internally it uses resources that also implement . However,there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. + The class implements the interface because internally it uses resources that also implement . However, there is no need to call unless performance or scalability testing indicates that, based on your usage patterns, your app's performance would be improved by disposing of tasks. For more information, see [Do I need to dispose of Tasks?](https://devblogs.microsoft.com/pfxteam/do-i-need-to-dispose-of-tasks/) in the Parallel Programming with .NET blog. ]]> diff --git a/xml/System.Threading/Interlocked.xml b/xml/System.Threading/Interlocked.xml index b3ff2d9d9d1..2bfdf93a0c1 100644 --- a/xml/System.Threading/Interlocked.xml +++ b/xml/System.Threading/Interlocked.xml @@ -2485,7 +2485,7 @@ If `comparand` and the value in `location1` are equal by reference, then `value` method. + This method is 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.