diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 7c98f5e6f4e..08f63d3780d 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -144,28 +144,28 @@ The delegate that represents the code to execute in the task. Initializes a new with the specified action. - object and launch a task is by calling the static or method. - - If a task with no action is needed just for the consumer of an API to have something to await, a should be used. - -## Examples - The following example uses the constructor to create tasks that retrieve the filenames in specified directories. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/ctor1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/ctor1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/ctor1.vb" id="Snippet1"::: - - The following example is identical, except that it used the method to instantiate and run the task in a single operation. The method returns the object that represents the task. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run2.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run2.vb" id="Snippet1"::: - + object and launch a task is by calling the static or method. + + If a task with no action is needed just for the consumer of an API to have something to await, a should be used. + +## Examples + The following example uses the constructor to create tasks that retrieve the filenames in specified directories. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/ctor1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/ctor1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/ctor1.vb" id="Snippet1"::: + + The following example is identical, except that it used the method to instantiate and run the task in a single operation. The method returns the object that represents the task. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run2.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run2.vb" id="Snippet1"::: + ]]> The argument is . @@ -215,20 +215,20 @@ The that the new task will observe. Initializes a new with the specified action and . - object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - - For more information, see [Task Parallelism (Task Parallel Library)](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). - -## Examples - The following example calls the constructor to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. The method is then called to start the task. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run4.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/run4.vb" id="Snippet4"::: - + object and launch a task is by calling the static and methods. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + + For more information, see [Task Parallelism (Task Parallel Library)](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Cancellation in Managed Threads](/dotnet/standard/threading/cancellation-in-managed-threads). + +## Examples + The following example calls the constructor to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. The method is then called to start the task. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run4.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run4.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/run4.vb" id="Snippet4"::: + ]]> The provided has already been disposed. @@ -278,11 +278,11 @@ The used to customize the task's behavior. Initializes a new with the specified action and creation options. - object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + ]]> The argument is null. @@ -346,18 +346,18 @@ An object representing data to be used by the action. Initializes a new with the specified action and state. - object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - -## Examples - The following example defines an array of 6-letter words. Each word is then passed as an argument to the constructor, whose delegate scrambles the characters in the word, then displays the original word and its scrambled version. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/startnew3.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/startnew3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/startnew3.vb" id="Snippet3"::: - + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + +## Examples + The following example defines an array of 6-letter words. Each word is then passed as an argument to the constructor, whose delegate scrambles the characters in the word, then displays the original word and its scrambled version. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/startnew3.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/startnew3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.ctor/vb/startnew3.vb" id="Snippet3"::: + ]]> The argument is null. @@ -409,13 +409,13 @@ The used to customize the task's behavior. Initializes a new with the specified action and creation options. - object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - - For more information, see [Task Parallelism (Task Parallel Library)](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Task Cancellation](/dotnet/standard/parallel-programming/task-cancellation). - + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + + For more information, see [Task Parallelism (Task Parallel Library)](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Task Cancellation](/dotnet/standard/parallel-programming/task-cancellation). + ]]> The that created has already been disposed. @@ -482,11 +482,11 @@ The that the new task will observe. Initializes a new with the specified action, state, and . - object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + ]]> The that created has already been disposed. @@ -552,11 +552,11 @@ The used to customize the task's behavior. Initializes a new with the specified action, state, and options. - object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + ]]> The argument is null. @@ -624,11 +624,11 @@ The used to customize the task's behavior. Initializes a new with the specified action, state, and options. - object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. - + object and launch a task is by calling the static method. The only advantage offered by this constructor is that it allows object instantiation to be separated from task invocation. + ]]> The that created has already been disposed. @@ -691,12 +691,12 @@ Gets the state object supplied when the was created, or null if none was supplied. An that represents the state data that was passed in to the task when it was created. - @@ -741,13 +741,13 @@ To retrieve the object's data, cast it back to the original type. Gets a task that has already completed successfully. The successfully completed task. - property is set to . To create a task that returns a value and runs to completion, call the method. - - Repeated attempts to retrieve this property value may not always return the same instance. - + property is set to . To create a task that returns a value and runs to completion, call the method. + + Repeated attempts to retrieve this property value may not always return the same instance. + ]]> @@ -805,12 +805,12 @@ To retrieve the object's data, cast it back to the original type. Configures an awaiter used to await this . An object used to await this task. - directly, continuation usually occurs in the same thread that created the task, depending on the async context. This behavior can be costly in terms of performance and can result in a deadlock on the UI thread. To avoid these problems, call `Task.ConfigureAwait(false)`. For more information, see [ConfigureAwait FAQ](https://devblogs.microsoft.com/dotnet/configureawait-faq/). - + directly, continuation usually occurs in the same thread that created the task, depending on the async context. This behavior can be costly in terms of performance and can result in a deadlock on the UI thread. To avoid these problems, call `Task.ConfigureAwait(false)`. For more information, see [ConfigureAwait FAQ](https://devblogs.microsoft.com/dotnet/configureawait-faq/). + ]]> ConfigureAwait FAQ @@ -907,24 +907,24 @@ When an asynchronous method awaits a directly Creates a continuation that executes asynchronously when the target completes. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - - - -## Examples - The following example defines a task that populates an array with 100 random date and time values. It uses the method to select the earliest and the latest date values once the array is fully populated. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.continuewith/vb/continuewith1.vb" id="Snippet1"::: - - Because a console application may terminate before the continuation task executes, the method is called to ensure that the continuation finishes executing before the example ends. - - For an additional example, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks). - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + + + +## Examples + The following example defines a task that populates an array with 100 random date and time values. It uses the method to select the earliest and the latest date values once the array is fully populated. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/ContinueWith/continuewith1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.continuewith/vb/continuewith1.vb" id="Snippet1"::: + + Because a console application may terminate before the continuation task executes, the method is called to ensure that the continuation finishes executing before the example ends. + + For an additional example, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks). + ]]> The argument is . @@ -992,11 +992,11 @@ When an asynchronous method awaits a directly Creates a continuation that receives caller-supplied state information and executes when the target completes. A new continuation task. - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting early due to cancellation. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting early due to cancellation. + ]]> The argument is . @@ -1049,11 +1049,11 @@ When an asynchronous method awaits a directly Creates a continuation that receives a cancellation token and executes asynchronously when the target completes. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The that created the token has already been disposed. @@ -1107,57 +1107,57 @@ When an asynchronous method awaits a directly Creates a continuation that executes when the target task completes according to the specified . A new continuation . - will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - - - -## Examples - The following example demonstrates using to specify that a continuation task should run synchronously when the antecedent task completes. (If the specified task has already completed by the time is called, the synchronous continuation will run on the thread calling .) - -```csharp - -public class TaskCounter -{ - private volatile int _count; - - public void Track(Task t) - { - if (t == null) throw new ArgumentNullException("t"); - Interlocked.Increment(ref _count); - t.ContinueWith(ct => Interlocked.Decrement(ref _count), TaskContinuationOptions.ExecuteSynchronously); - } - - public int NumberOfActiveTasks { get { return _count; } } -} - -``` - -```vb - -Public Class TaskCounter - Private _count as Integer - - Public Sub Track(ByVal t as Task) - If t is Nothing Then Throw New ArgumentNullException("t") - Interlocked.Increment(_count) - t.ContinueWith(Sub(ct) - Interlocked.Decrement(_count) - End Sub, - TaskContinuationOptions.ExecuteSynchronously) - End Sub - - Public ReadOnly Property NumberOfActiveTasks As Integer - Get - Return _count - End Get - End Property -End Class - -``` - + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + + + +## Examples + The following example demonstrates using to specify that a continuation task should run synchronously when the antecedent task completes. (If the specified task has already completed by the time is called, the synchronous continuation will run on the thread calling .) + +```csharp + +public class TaskCounter +{ + private volatile int _count; + + public void Track(Task t) + { + if (t == null) throw new ArgumentNullException("t"); + Interlocked.Increment(ref _count); + t.ContinueWith(ct => Interlocked.Decrement(ref _count), TaskContinuationOptions.ExecuteSynchronously); + } + + public int NumberOfActiveTasks { get { return _count; } } +} + +``` + +```vb + +Public Class TaskCounter + Private _count as Integer + + Public Sub Track(ByVal t as Task) + If t is Nothing Then Throw New ArgumentNullException("t") + Interlocked.Increment(_count) + t.ContinueWith(Sub(ct) + Interlocked.Decrement(_count) + End Sub, + TaskContinuationOptions.ExecuteSynchronously) + End Sub + + Public ReadOnly Property NumberOfActiveTasks As Integer + Get + Return _count + End Get + End Property +End Class + +``` + ]]> The argument is null. @@ -1211,18 +1211,18 @@ End Class Creates a continuation that executes asynchronously when the target completes. The continuation uses a specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The has been disposed. - The argument is . - - -or- - + The argument is . + + -or- + The argument is null. @@ -1290,11 +1290,11 @@ End Class Creates a continuation that receives caller-supplied state information and a cancellation token and that executes asynchronously when the target completes. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The argument is . @@ -1365,11 +1365,11 @@ End Class Creates a continuation that receives caller-supplied state information and executes when the target completes. The continuation executes based on a set of specified conditions. A new continuation . - will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + ]]> The argument is . @@ -1440,11 +1440,11 @@ End Class Creates a continuation that receives caller-supplied state information and executes asynchronously when the target completes. The continuation uses a specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The argument is . @@ -1501,57 +1501,57 @@ End Class Creates a continuation that executes when the target task competes according to the specified . The continuation receives a cancellation token and uses a specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - -## Examples - The following is an example of using ContinueWith to run work both in the background and on the user interface threads. - -```csharp - -private void Button1_Click(object sender, EventArgs e) -{ - var backgroundScheduler = TaskScheduler.Default; - var uiScheduler = TaskScheduler.FromCurrentSynchronizationContext(); - Task.Factory.StartNew(delegate { DoBackgroundComputation(); }, - backgroundScheduler). - ContinueWith(delegate { UpdateUI(); }, uiScheduler). - ContinueWith(delegate { DoAnotherBackgroundComputation(); }, - backgroundScheduler). - ContinueWith(delegate { UpdateUIAgain(); }, uiScheduler); -} - -``` - -```vb - -Private Sub Button1_Click(ByVal sender As System.Object, - ByVal e As System.EventArgs) Handles Button1.Click - Dim backgroundScheduler = TaskScheduler.Default - Dim uiScheduler = TaskScheduler.FromCurrentSynchronizationContext() - - Task.Factory.StartNew(Sub() - DoBackgroundComputation() - End Sub, backgroundScheduler).ContinueWith(Sub(t) - UpdateUI() - End Sub, uiScheduler).ContinueWith(Sub(t) - DoAnotherBackgroundComputation() - End Sub, backgroundScheduler).ContinueWith(Sub(t) - UpdateUIAgain() - End Sub, uiScheduler) -End Sub - -``` - + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + +## Examples + The following is an example of using ContinueWith to run work both in the background and on the user interface threads. + +```csharp + +private void Button1_Click(object sender, EventArgs e) +{ + var backgroundScheduler = TaskScheduler.Default; + var uiScheduler = TaskScheduler.FromCurrentSynchronizationContext(); + Task.Factory.StartNew(delegate { DoBackgroundComputation(); }, + backgroundScheduler). + ContinueWith(delegate { UpdateUI(); }, uiScheduler). + ContinueWith(delegate { DoAnotherBackgroundComputation(); }, + backgroundScheduler). + ContinueWith(delegate { UpdateUIAgain(); }, uiScheduler); +} + +``` + +```vb + +Private Sub Button1_Click(ByVal sender As System.Object, + ByVal e As System.EventArgs) Handles Button1.Click + Dim backgroundScheduler = TaskScheduler.Default + Dim uiScheduler = TaskScheduler.FromCurrentSynchronizationContext() + + Task.Factory.StartNew(Sub() + DoBackgroundComputation() + End Sub, backgroundScheduler).ContinueWith(Sub(t) + UpdateUI() + End Sub, uiScheduler).ContinueWith(Sub(t) + DoAnotherBackgroundComputation() + End Sub, backgroundScheduler).ContinueWith(Sub(t) + UpdateUIAgain() + End Sub, uiScheduler) +End Sub + +``` + ]]> The that created the token has already been disposed. - The argument is null. - - -or- - + The argument is null. + + -or- + The argument is null. The argument specifies an invalid value for . @@ -1624,11 +1624,11 @@ End Sub Creates a continuation that receives caller-supplied state information and a cancellation token and that executes when the target completes. The continuation executes based on a set of specified conditions and uses a specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + ]]> The argument is . @@ -1692,20 +1692,20 @@ End Sub Creates a continuation that executes asynchronously when the target completes and returns a value. A new continuation task. - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - - - -## Examples - The following example shows how to use the ContinueWith method: - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/continuationsimple.cs" id="Snippet03"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/continuationsimple.fs" id="Snippet03"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/continuationsimple.vb" id="Snippet03"::: - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + + + +## Examples + The following example shows how to use the ContinueWith method: + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/continuationsimple.cs" id="Snippet03"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/continuationsimple.fs" id="Snippet03"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/continuationsimple.vb" id="Snippet03"::: + ]]> The has been disposed. @@ -1777,11 +1777,11 @@ End Sub Creates a continuation that receives caller-supplied state information and executes asynchronously when the target completes and returns a value. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The argument is . @@ -1845,17 +1845,17 @@ End Sub Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation receives a cancellation token. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> - The has been disposed. - - -or- - + The has been disposed. + + -or- + The that created the token has already been disposed. The argument is null. @@ -1918,11 +1918,11 @@ End Sub Creates a continuation that executes according to the specified continuation options and returns a value. A new continuation . - will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + ]]> The has been disposed. @@ -1988,18 +1988,18 @@ End Sub Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation uses a specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The has been disposed. - The argument is null. - - -or- - + The argument is null. + + -or- + The argument is null. @@ -2070,11 +2070,11 @@ End Sub Creates a continuation that executes asynchronously when the target completes and returns a value. The continuation receives caller-supplied state information and a cancellation token. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The argument is . @@ -2148,11 +2148,11 @@ End Sub Creates a continuation that executes based on the specified task continuation options when the target completes. The continuation receives caller-supplied state information. A new continuation . - will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - + will not be scheduled for execution until the current task has completed. If the continuation criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + ]]> The argument is . @@ -2234,11 +2234,11 @@ End Sub Creates a continuation that executes asynchronously when the target completes. The continuation receives caller-supplied state information and uses a specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. - + will not be scheduled for execution until the current task has completed, whether it completes due to running to completion successfully, faulting due to an unhandled exception, or exiting out early due to being canceled. + ]]> The argument is . @@ -2306,29 +2306,29 @@ End Sub Creates a continuation that executes according to the specified continuation options and returns a value. The continuation is passed a cancellation token and uses a specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - -## Examples - The following example shows how to use the ContinueWith method with continuation options: - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/continuationoptions.cs" id="Snippet04"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/continuationoptions.fs" id="Snippet04"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/continuationoptions.vb" id="Snippet04"::: - + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + +## Examples + The following example shows how to use the ContinueWith method with continuation options: + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/continuationoptions.cs" id="Snippet04"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/continuationoptions.fs" id="Snippet04"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/continuationoptions.vb" id="Snippet04"::: + ]]> - The has been disposed. - - -or- - + The has been disposed. + + -or- + The that created the token has already been disposed. - The argument is null. - - -or- - + The argument is null. + + -or- + The argument is null. The argument specifies an invalid value for . @@ -2412,11 +2412,11 @@ End Sub Creates a continuation that executes based on the specified task continuation options when the target completes and returns a value. The continuation receives caller-supplied state information and a cancellation token and uses the specified scheduler. A new continuation . - will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. - + will not be scheduled for execution until the current task has completed. If the criteria specified through the `continuationOptions` parameter are not met, the continuation task will be canceled instead of scheduled. + ]]> The argument is . @@ -2508,13 +2508,13 @@ End Sub Returns the ID of the currently executing . An integer that was assigned by the system to the currently-executing task. - is a `static` (`Shared` in Visual Basic) property that is used to get the identifier of the currently executing task from the code that the task is executing. It differs from the property, which returns the identifier of a particular instance. If you attempt to retrieve the value from outside the code that a task is executing, the property returns `null`. - - Note that although collisions are very rare, task identifiers are not guaranteed to be unique. - + is a `static` (`Shared` in Visual Basic) property that is used to get the identifier of the currently executing task from the code that the task is executing. It differs from the property, which returns the identifier of a particular instance. If you attempt to retrieve the value from outside the code that a task is executing, the property returns `null`. + + Note that although collisions are very rare, task identifiers are not guaranteed to be unique. + ]]> @@ -2575,39 +2575,39 @@ End Sub Creates a task that completes after a specified number of milliseconds. A task that represents the time delay. - method is typically used to delay the operation of all or part of a task for a specified time interval. Most commonly, the time delay is introduced: - -- At the beginning of the task, as the following example shows. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay5.vb" id="Snippet5"::: - -- Sometime while the task is executing. In this case, the call to the method executes as a child task within a task, as the following example shows. Note that since the task that calls the method executes asynchronously, the parent task must wait for it to complete by using the `await` keyword. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay5.vb" id="Snippet7"::: - - After the specified time delay, the task is completed in the state. - - This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `millisecondsDelay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. - -> [!NOTE] -> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - - -## Examples - The following example shows a simple use of the method. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay1.vb" id="Snippet1"::: - + method is typically used to delay the operation of all or part of a task for a specified time interval. Most commonly, the time delay is introduced: + +- At the beginning of the task, as the following example shows. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay5.vb" id="Snippet5"::: + +- Sometime while the task is executing. In this case, the call to the method executes as a child task within a task, as the following example shows. Note that since the task that calls the method executes asynchronously, the parent task must wait for it to complete by using the `await` keyword. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay5.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay5.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay5.vb" id="Snippet7"::: + + After the specified time delay, the task is completed in the state. + + This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `millisecondsDelay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. + +> [!NOTE] +> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). + + + +## Examples + The following example shows a simple use of the method. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay1.vb" id="Snippet1"::: + ]]> The argument is less than -1. @@ -2658,34 +2658,34 @@ End Sub Creates a task that completes after a specified time interval. A task that represents the time delay. - state. - - For usage scenarios and additional examples, see the documentation for the overload. - - This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `delay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. - -> [!NOTE] -> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - - -## Examples - The following example shows a simple use of the method. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay2.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay2.vb" id="Snippet2"::: - + state. + + For usage scenarios and additional examples, see the documentation for the overload. + + This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `delay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. + +> [!NOTE] +> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). + + + +## Examples + The following example shows a simple use of the method. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay2.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay2.vb" id="Snippet2"::: + ]]> - represents a negative time interval other than . - - -or- - + represents a negative time interval other than . + + -or- + The argument's property is greater than 4294967294 on .NET 6 and later versions, or Int32.MaxValue on all previous versions. @@ -2736,29 +2736,29 @@ End Sub Creates a cancellable task that completes after a specified number of milliseconds. A task that represents the time delay. - exception results, and the task is completed in the state. Otherwise, the task is completed in the state once the specified time delay has elapsed. - - For usage scenarios and additional examples, see the documentation for the overload. - - This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `millisecondsDelay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. - -> [!NOTE] -> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - -## Examples - The following example launches a task that includes a call to the method with a one second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay3.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay3.vb" id="Snippet3"::: - + exception results, and the task is completed in the state. Otherwise, the task is completed in the state once the specified time delay has elapsed. + + For usage scenarios and additional examples, see the documentation for the overload. + + This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `millisecondsDelay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. + +> [!NOTE] +> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). + +## Examples + The following example launches a task that includes a call to the method with a one second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay3.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay3.vb" id="Snippet3"::: + ]]> The argument is less than -1. - The task has been canceled. + The task has been canceled. This exception is stored into the returned task. The provided has already been disposed. @@ -2809,42 +2809,42 @@ End Sub Creates a cancellable task that completes after a specified time interval. A task that represents the time delay. - exception results, and the task is completed in the state. Otherwise, the task is completed in the state once the specified time delay has elapsed. - - For usage scenarios and additional examples, see the documentation for the overload. - - This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `delay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. - -> [!NOTE] -> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). - - - -## Examples - The following example launches a task that includes a call to the method with a 1.5 second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay4.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay4.vb" id="Snippet4"::: - - Note that this example includes a potential race condition: it depends on the task asynchronously executing the delay when the token is cancelled. Although the 1.5 second delay from the call to the method makes that assumption likely, it is nevertheless possible that the call to the method could return before the token is cancelled. In that case, the example produces the following output: - -``` -Task t Status: RanToCompletion, Result: 42 -``` - + exception results, and the task is completed in the state. Otherwise, the task is completed in the state once the specified time delay has elapsed. + + For usage scenarios and additional examples, see the documentation for the overload. + + This method depends on the system clock. This means that the time delay will approximately equal the resolution of the system clock if the `delay` argument is less than the resolution of the system clock, which is approximately 15 milliseconds on Windows systems. + +> [!NOTE] +> The system clock that is used is the same clock used by [GetTickCount](/windows/win32/api/sysinfoapi/nf-sysinfoapi-gettickcount), which is not affected by changes made with [timeBeginPeriod](/windows/win32/api/timeapi/nf-timeapi-timebeginperiod) and [timeEndPeriod](/windows/win32/api/timeapi/nf-timeapi-timeendperiod). + + + +## Examples + The following example launches a task that includes a call to the method with a 1.5 second delay. Before the delay interval elapses, the token is cancelled. The output from the example shows that, as a result, a is thrown, and the tasks' property is set to . + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Delay/delay4.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Delay/delay4.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.delay/vb/delay4.vb" id="Snippet4"::: + + Note that this example includes a potential race condition: it depends on the task asynchronously executing the delay when the token is cancelled. Although the 1.5 second delay from the call to the method makes that assumption likely, it is nevertheless possible that the call to the method could return before the token is cancelled. In that case, the example produces the following output: + +``` +Task t Status: RanToCompletion, Result: 42 +``` + ]]> - represents a negative time interval other than . - - -or- - + represents a negative time interval other than . + + -or- + The argument's property is greater than 4294967294 on .NET 6 and later versions, or Int32.MaxValue on all previous versions. - The task has been canceled. + The task has been canceled. This exception is stored into the returned task. The provided has already been disposed. @@ -2993,11 +2993,11 @@ Task t Status: RanToCompletion, Result: 42 Releases all resources used by the current instance of the class. - class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .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. - + class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .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 task is not in one of the final states: , , or . @@ -3045,11 +3045,11 @@ Task t Status: RanToCompletion, Result: 42 A Boolean value that indicates whether this method is being called due to a call to . Disposes the , releasing all of its unmanaged resources. - class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .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. - + class implements the interface because internally it uses resources that also implement . However, particularly if your app targets the .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 task is not in one of the final states: , , or . @@ -3108,11 +3108,11 @@ Task t Status: RanToCompletion, Result: 42 Gets the that caused the to end prematurely. If the completed successfully or has not yet thrown any exceptions, this will return . The that caused the to end prematurely. - 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). - + 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). + ]]> @@ -3158,29 +3158,29 @@ Task t Status: RanToCompletion, Result: 42 Provides access to factory methods for creating and configuring and instances. A factory object that can create a variety of and objects. - class that is identical to the one created by calling the parameterless constructor. It has the following property values: - -|Property|Value| -|--------------|-----------| -||| -||| -||| -||`null`, or | - - 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 the .NET Framework 4.5, 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. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Factory/factory1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.factory/vb/factory1.vb" id="Snippet1"::: - + class that is identical to the one created by calling the parameterless constructor. It has the following property values: + +|Property|Value| +|--------------|-----------| +||| +||| +||| +||`null`, or | + + 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 the .NET Framework 4.5, 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. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Factory/factory1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Factory/factory1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.factory/vb/factory1.vb" id="Snippet1"::: + ]]> @@ -3335,11 +3335,11 @@ Task t Status: RanToCompletion, Result: 42 Creates a that has completed with a specified exception. The faulted task. - object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. For an example, see the overload. - + object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. For an example, see the overload. + ]]> @@ -3399,20 +3399,20 @@ Task t Status: RanToCompletion, Result: 42 Creates a that's completed with a specified exception. The faulted task. - object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. The example provides an illustration. - - - -## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb" id="Snippet1"::: - + object whose property is and whose property contains `exception`. The method is commonly used when you immediately know that the work that a task performs will throw an exception before executing a longer code path. The example provides an illustration. + + + +## Examples + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a faulted task if a particular subdirectory does not exist. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb" id="Snippet1"::: + ]]> @@ -3473,23 +3473,23 @@ Task t Status: RanToCompletion, Result: 42 Creates a that's completed successfully with the specified result. The successfully completed task. - object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. - -To create a `Task` object that does not return a value, retrieve the `Task` object from the property. - -Starting in .NET 6, for some `TResult` types and some result values, this method may return a cached singleton object rather than allocating a new object. - -## Examples - The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb" id="Snippet1"::: - + object whose property is `result` and whose property is . The method is commonly used when the return value of a task is immediately known without executing a longer code path. The example provides an illustration. + +To create a `Task` object that does not return a value, retrieve the `Task` object from the property. + +Starting in .NET 6, for some `TResult` types and some result values, this method may return a cached singleton object rather than allocating a new object. + +## Examples + The following example is a command-line utility that calculates the number of bytes in the files in each directory whose name is passed as a command-line argument. Rather than executing a longer code path that instantiates a object and retrieves the value of its property for each file in the directory, the example simply calls the method to create a task whose property is zero (0) if a directory has no files. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/FromExceptionTResult/fromresult1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.fromresult/vb/fromresult1.vb" id="Snippet1"::: + ]]> @@ -3543,12 +3543,12 @@ Starting in .NET 6, for some `TResult` types and some result values, this method Gets an awaiter used to await this . An awaiter instance. - @@ -3594,13 +3594,13 @@ This method is intended for compiler use rather than use directly in code. Gets an ID for this instance. The identifier that is assigned by the system to this instance. - property. - + property. + ]]> @@ -3648,20 +3648,20 @@ This method is intended for compiler use rather than use directly in code. if the task has completed due to being canceled; otherwise . - will complete in the state under any of the following conditions: - -- Its was marked for cancellation before the task started executing, - -- The task acknowledged the cancellation request on its already signaled by throwing an that bears the same . - -- The task acknowledged the cancellation request on its already signaled by calling the method on the . - -> [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. - + will complete in the state under any of the following conditions: + +- Its was marked for cancellation before the task started executing, + +- The task acknowledged the cancellation request on its already signaled by throwing an that bears the same . + +- The task acknowledged the cancellation request on its already signaled by calling the method on the . + +> [!IMPORTANT] +> Retrieving the value of the property does not block the calling thread until the task has completed. + ]]> @@ -3717,13 +3717,13 @@ This method is intended for compiler use rather than use directly in code. if the task has completed (that is, the task is in one of the three final states: , , or ); otherwise, . - [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. - + [!IMPORTANT] +> Retrieving the value of the property does not block the calling thread until the task has completed. + ]]> @@ -3819,14 +3819,14 @@ This method is intended for compiler use rather than use directly in code. if the task has thrown an unhandled exception; otherwise . - is `true`, the task's is equal to , and its property will be non-null. - -> [!IMPORTANT] -> Retrieving the value of the property does not block the calling thread until the task has completed. - + is `true`, the task's is equal to , and its property will be non-null. + +> [!IMPORTANT] +> Retrieving the value of the property does not block the calling thread until the task has completed. + ]]> @@ -3840,11 +3840,11 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the ThreadPool and returns a task or handle for that work. - method provides a set of overloads that make it easy to start a task by using default values. It is a lightweight alternative to the overloads. - + method provides a set of overloads that make it easy to start a task by using default values. It is a lightweight alternative to the overloads. + ]]> @@ -3894,44 +3894,44 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a object that represents that work. A task that represents the work queued to execute in the ThreadPool. - method allows you to create and execute a task in a single method call and is a simpler alternative to the method. It creates a task with the following default values: - -- Its cancellation token is . - -- Its property value is . - -- It uses the default task scheduler. - - For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - - - -## Examples - The following example defines a `ShowThreadInfo` method that displays the of the current thread. It is called directly from the application thread, and is called from the delegate passed to the method. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run11.cs" id="Snippet11"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run11.fs" id="Snippet11"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run11.vb" id="Snippet11"::: - - The following example is similar to the previous one, except that it uses a lambda expression to define the code that the task is to execute. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run6.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run6.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run6.vb" id="Snippet3"::: - - The examples show that the asynchronous task executes on a different thread than the main application thread. - - The call to the method ensures that the task completes and displays its output before the application ends. Otherwise, it is possible that the `Main` method will complete before the task finishes. - - The following example illustrates the method. It defines an array of directory names and starts a separate task to retrieve the file names in each directory. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run2.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run2.vb" id="Snippet1"::: - + method allows you to create and execute a task in a single method call and is a simpler alternative to the method. It creates a task with the following default values: + +- Its cancellation token is . + +- Its property value is . + +- It uses the default task scheduler. + + For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + + + +## Examples + The following example defines a `ShowThreadInfo` method that displays the of the current thread. It is called directly from the application thread, and is called from the delegate passed to the method. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run11.cs" id="Snippet11"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run11.fs" id="Snippet11"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run11.vb" id="Snippet11"::: + + The following example is similar to the previous one, except that it uses a lambda expression to define the code that the task is to execute. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run6.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run6.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run6.vb" id="Snippet3"::: + + The examples show that the asynchronous task executes on a different thread than the main application thread. + + The call to the method ensures that the task completes and displays its output before the application ends. Otherwise, it is possible that the `Main` method will complete before the task finishes. + + The following example illustrates the method. It defines an array of directory names and starts a separate task to retrieve the file names in each directory. All tasks write the file names to a single object. The example then calls the method to ensure that all tasks have completed, and then displays a count of the total number of file names written to the object. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run2.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run2.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run2.vb" id="Snippet1"::: + ]]> The parameter was . @@ -3991,11 +3991,11 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a proxy for the task returned by . A task that represents a proxy for the task returned by . - The parameter was . @@ -4049,32 +4049,32 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a object that represents that work. A cancellation token allows the work to be cancelled if it has not yet started. A task that represents the work queued to execute in the thread pool. - state and throws a exception. - - The method is a simpler alternative to the method. It creates a task with the following default values: - -- Its property value is . - -- It uses the default task scheduler. - - For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - - - -## Examples - The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run41.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run41.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run4.vb" id="Snippet4"::: - + state and throws a exception. + + The method is a simpler alternative to the method. It creates a task with the following default values: + +- Its property value is . + +- It uses the default task scheduler. + + For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + + + +## Examples + The following example calls the method to create a task that iterates the files in the C:\Windows\System32 directory. The lambda expression calls the method to add information about each file to a object. Each detached nested task invoked by the loop checks the state of the cancellation token and, if cancellation is requested, calls the method. The method throws an exception that is handled in a `catch` block when the calling thread calls the method. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run41.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run41.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run4.vb" id="Snippet4"::: + ]]> The parameter was . - The task has been canceled. + The task has been canceled. This exception is stored into the returned task. The associated with was disposed. Exception Handling (Task Parallel Library) @@ -4134,15 +4134,15 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a proxy for the task returned by . A cancellation token allows the work to be cancelled if it has not yet started. A task that represents a proxy for the task returned by . - The parameter was . - The task has been canceled. + The task has been canceled. This exception is stored into the returned task. The associated with was disposed. Task Cancellation Exception Handling (Task Parallel Library) @@ -4212,11 +4212,11 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a proxy for the returned by . A cancellation token allows the work to be cancelled if it has not yet started. A that represents a proxy for the returned by . - The parameter was . @@ -4279,30 +4279,30 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a object that represents that work. A cancellation token allows the work to be cancelled if it has not yet started. A task object that represents the work queued to execute in the thread pool. - method is a simpler alternative to the method. It creates a task with the following default values: - -- Its cancellation token is . - -- Its property value is . - -- It uses the default task scheduler. - - For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - - - -## Examples - The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run31.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run31.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run3.vb" id="Snippet2"::: - - The regular expression `\p{P}*\s+` matches zero, one, or more punctuation characters followed by one or more white-space characters. It assumes that the total number of matches equals the approximate word count. - + method is a simpler alternative to the method. It creates a task with the following default values: + +- Its cancellation token is . + +- Its property value is . + +- It uses the default task scheduler. + + For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + + + +## Examples + The following example counts the approximate number of words in text files that represent published books. Each task is responsible for opening a file, reading its entire contents asynchronously, and calculating the word count by using a regular expression. The method is called to ensure that all tasks have completed before displaying the word count of each book to the console. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/run31.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/run31.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/run3.vb" id="Snippet2"::: + + The regular expression `\p{P}*\s+` matches zero, one, or more punctuation characters followed by one or more white-space characters. It assumes that the total number of matches equals the approximate word count. + ]]> The parameter is . @@ -4375,15 +4375,15 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a proxy for the returned by . A that represents a proxy for the returned by . - The parameter was . - The task has been canceled. + The task has been canceled. This exception is stored into the returned task. The associated with was disposed. Task Cancellation Exception Handling (Task Parallel Library) @@ -4447,42 +4447,42 @@ This method is intended for compiler use rather than use directly in code. Queues the specified work to run on the thread pool and returns a object that represents that work. A that represents the work queued to execute in the thread pool. - state and throws a exception. - - The method is a simpler alternative to the method. It creates a task with the following default values: - -- Its property value is . - -- It uses the default task scheduler. - - For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - - - -## Examples - The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example shows possible output. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run7.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run7.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run7.vb" id="Snippet7"::: - - Instead of using the property to examine exceptions, the example iterates all tasks to determine which have completed successfully and which have been cancelled. For those that have completed, it displays the value returned by the task. - - Because cancellation is cooperative, each task can decide how to respond to cancellation. The following example is like the first, except that, once the token is cancelled, tasks return the number of iterations they've completed rather than throw an exception. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run28.cs" id="Snippet28"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run28.fs" id="Snippet28"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run28.vb" id="Snippet28"::: - - The example still must handle the exception, since any tasks that have not started when cancellation is requested still throw an exception. - + state and throws a exception. + + The method is a simpler alternative to the method. It creates a task with the following default values: + +- Its property value is . + +- It uses the default task scheduler. + + For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + + + +## Examples + The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example shows possible output. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run7.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run7.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run7.vb" id="Snippet7"::: + + Instead of using the property to examine exceptions, the example iterates all tasks to determine which have completed successfully and which have been cancelled. For those that have completed, it displays the value returned by the task. + + Because cancellation is cooperative, each task can decide how to respond to cancellation. The following example is like the first, except that, once the token is cancelled, tasks return the number of iterations they've completed rather than throw an exception. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run28.cs" id="Snippet28"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run28.fs" id="Snippet28"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run28.vb" id="Snippet28"::: + + The example still must handle the exception, since any tasks that have not started when cancellation is requested still throw an exception. + ]]> The parameter is . - The task has been canceled. + The task has been canceled. This exception is stored into the returned task. The associated with was disposed. Task Cancellation Exception Handling (Task Parallel Library) @@ -4539,22 +4539,22 @@ This method is intended for compiler use rather than use directly in code. Runs the synchronously on the current . - method are associated with the current and are run on the calling thread. If the target scheduler does not support running this task on the calling thread, the task will be scheduled for execution on the scheduler, and the calling thread will block until the task has completed execution. Even though the task runs synchronously, the calling thread should still call to handle any exceptions that the task might throw. For more information on exception handling, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - - Tasks executed by calling the method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. - - - -## Examples - The following example compares a task executed by calling the method with one executed asynchronously. In both cases, the tasks execute identical lambda expressions that display the task ID and the ID of the thread on which the task is running. The task calculates the sum of the integers between 1 and 1,000,000. As the output from the example shows, the task executed by calling the method runs on the application thread, while the asynchronous task does not. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/RunSynchronously/runsynchronously1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/RunSynchronously/runsynchronously1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.runsynchronously/vb/runsynchronously1.vb" id="Snippet1"::: - + method are associated with the current and are run on the calling thread. If the target scheduler does not support running this task on the calling thread, the task will be scheduled for execution on the scheduler, and the calling thread will block until the task has completed execution. Even though the task runs synchronously, the calling thread should still call to handle any exceptions that the task might throw. For more information on exception handling, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + + Tasks executed by calling the method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. + + + +## Examples + The following example compares a task executed by calling the method with one executed asynchronously. In both cases, the tasks execute identical lambda expressions that display the task ID and the ID of the thread on which the task is running. The task calculates the sum of the integers between 1 and 1,000,000. As the output from the example shows, the task executed by calling the method runs on the application thread, while the asynchronous task does not. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/RunSynchronously/runsynchronously1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/RunSynchronously/runsynchronously1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.runsynchronously/vb/runsynchronously1.vb" id="Snippet1"::: + ]]> The instance has been disposed. @@ -4606,13 +4606,13 @@ This method is intended for compiler use rather than use directly in code. The scheduler on which to attempt to run this task inline. Runs the synchronously on the provided. - method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. - - If the target scheduler does not support running this task on the current thread, the task will be scheduled for execution on the scheduler, and the current thread will block until the task has completed execution. Because of this, the calling thread does not need to call a method such as to ensure that the task has completed execution. For more information on exception handling for task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - + method are instantiated by calling a or class constructor. The task to be run synchronously must be in the state. A task may be started and run only once. Any attempts to schedule a task a second time results in an exception. + + If the target scheduler does not support running this task on the current thread, the task will be scheduled for execution on the scheduler, and the current thread will block until the task has completed execution. Because of this, the calling thread does not need to call a method such as to ensure that the task has completed execution. For more information on exception handling for task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + ]]> The instance has been disposed. @@ -4673,24 +4673,24 @@ This method is intended for compiler use rather than use directly in code. Starts the , scheduling it for execution to the current . - is used to execute a task that has been created by calling one of the constructors. Typically, you do this when you need to separate the task's creation from its execution, such as when you conditionally execute tasks that you've created. For the more common case in which you don't need to separate task instantiation from execution, we recommend that you call an overload of the or method. - - For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). - - - -## Examples - The following example calls the constructor to instantiate a new object that displays its task ID and managed thread ID and then executes a loop. It then calls the method to execute the task. Since this is a console app, the call to the method is necessary to prevent the app from terminating before the task finishes execution. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Start/Start1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Start/Start1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.start/vb/Start1.vb" id="Snippet1"::: - + is used to execute a task that has been created by calling one of the constructors. Typically, you do this when you need to separate the task's creation from its execution, such as when you conditionally execute tasks that you've created. For the more common case in which you don't need to separate task instantiation from execution, we recommend that you call an overload of the or method. + + For information on handling exceptions thrown by task operations, see [Exception Handling](/dotnet/standard/parallel-programming/exception-handling-task-parallel-library). + + + +## Examples + The following example calls the constructor to instantiate a new object that displays its task ID and managed thread ID and then executes a loop. It then calls the method to execute the task. Since this is a console app, the call to the method is necessary to prevent the app from terminating before the task finishes execution. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Start/Start1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Start/Start1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.start/vb/Start1.vb" id="Snippet1"::: + ]]> The instance has been disposed. @@ -4742,13 +4742,13 @@ This method is intended for compiler use rather than use directly in code. The with which to associate and execute this task. Starts the , scheduling it for execution to the specified . - The argument is . @@ -4799,22 +4799,22 @@ This method is intended for compiler use rather than use directly in code. Gets the of this task. The current of this task instance. - property does not block the calling thread until the task has completed. - - For more information and an example, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks) and [How to: Cancel a Task and Its Children](/dotnet/standard/parallel-programming/how-to-cancel-a-task-and-its-children). - - - -## Examples - The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether it completed successfully or was cancelled. For those that completed, it displays the value returned by the task. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run7.cs" id="Snippet7"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run7.fs" id="Snippet7"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run7.vb" id="Snippet7"::: - + property does not block the calling thread until the task has completed. + + For more information and an example, see [Chaining Tasks by Using Continuation Tasks](/dotnet/standard/parallel-programming/chaining-tasks-by-using-continuation-tasks) and [How to: Cancel a Task and Its Children](/dotnet/standard/parallel-programming/how-to-cancel-a-task-and-its-children). + + + +## Examples + The following example creates 20 tasks that will loop until a counter is incremented to a value of 2 million. When the first 10 tasks reach 2 million, the cancellation token is cancelled, and any tasks whose counters have not reached 2 million are cancelled. The example then examines the property of each task to indicate whether it completed successfully or was cancelled. For those that completed, it displays the value returned by the task. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/.ctor/Run7.cs" id="Snippet7"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/.ctor/Run7.fs" id="Snippet7"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.run/vb/Run7.vb" id="Snippet7"::: + ]]> @@ -4863,11 +4863,11 @@ This method is intended for compiler use rather than use directly in code. Gets a that can be used to wait for the task to complete. A that can be used to wait for the task to complete. - is preferable to using for similar functionality. For more information, see the "Waiting on Tasks" section in [Task-based Asynchronous Programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Using TPL with Other Asynchronous Patterns](/dotnet/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns). - + is preferable to using for similar functionality. For more information, see the "Waiting on Tasks" section in [Task-based Asynchronous Programming](/dotnet/standard/parallel-programming/task-based-asynchronous-programming) and [Using TPL with Other Asynchronous Patterns](/dotnet/standard/parallel-programming/using-tpl-with-other-asynchronous-patterns). + ]]> The has been disposed. @@ -4918,12 +4918,12 @@ This method is intended for compiler use rather than use directly in code. if the operation completed synchronously; otherwise, . - instance is cast to an interface. - + instance is cast to an interface. + ]]> @@ -4979,25 +4979,25 @@ This member is an explicit interface member implementation. It can be used only Waits for the to complete execution. - is a synchronization method that causes the calling thread to wait until the current task has completed. If the current task has not started execution, the Wait method attempts to remove the task from the scheduler and execute it inline on the current thread. If it is unable to do that, or if the current task has already started execution, it blocks the calling thread until the task completes. For more information, see [Task.Wait and "Inlining"](https://devblogs.microsoft.com/pfxteam/task-wait-and-inlining/) in the Parallel Programming with .NET blog. - -## Examples - The following example starts a task that generates one million random integers between 0 and 100 and computes their mean. The example uses the method to ensure that the task completes before the application terminates. Otherwise, because this is a console application, the example would terminate before the task can compute and display the mean. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait1.vb" id="Snippet1"::: - + is a synchronization method that causes the calling thread to wait until the current task has completed. If the current task has not started execution, the Wait method attempts to remove the task from the scheduler and execute it inline on the current thread. If it is unable to do that, or if the current task has already started execution, it blocks the calling thread until the task completes. For more information, see [Task.Wait and "Inlining"](https://devblogs.microsoft.com/pfxteam/task-wait-and-inlining/) in the Parallel Programming with .NET blog. + +## Examples + The following example starts a task that generates one million random integers between 0 and 100 and computes their mean. The example uses the method to ensure that the task completes before the application terminates. Otherwise, because this is a console application, the example would terminate before the task can compute and display the mean. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait1.vb" id="Snippet1"::: + ]]> The has been disposed. - The task was canceled. The collection contains a object. - - -or- - + The task was canceled. The collection contains a object. + + -or- + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. Task.Wait and "Inlining" @@ -5048,35 +5048,35 @@ This member is an explicit interface member implementation. It can be used only if the completed execution within the allotted time; otherwise, . - is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: - -- The task completes successfully. - -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - -- The interval defined by `millisecondsTimeout` elapses. In this case, the current thread resumes execution and the method returns `false`. - - - -## Examples - The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/Wait5.cs" id="Snippet5"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/Wait5.fs" id="Snippet5"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/Wait5.vb" id="Snippet5"::: - + is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: + +- The task completes successfully. + +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. + +- The interval defined by `millisecondsTimeout` elapses. In this case, the current thread resumes execution and the method returns `false`. + + + +## Examples + The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/Wait5.cs" id="Snippet5"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/Wait5.fs" id="Snippet5"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/Wait5.vb" id="Snippet5"::: + ]]> The has been disposed. is a negative number other than -1, which represents an infinite time-out. - The task was canceled. The collection contains a object. - - -or- - + The task was canceled. The collection contains a object. + + -or- + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. @@ -5124,33 +5124,33 @@ This member is an explicit interface member implementation. It can be used only A cancellation token to observe while waiting for the task to complete. Waits for the to complete execution. The wait terminates if a cancellation token is canceled before the task completes. - method creates a cancelable wait; that is, it causes the current thread to wait until one of the following occurs: - -- The task completes. - -- The cancellation token is canceled. In this case, the call to the method throws an . - -> [!NOTE] -> Canceling the `cancellationToken` cancellation token has no effect on the running task unless it has also been passed the cancellation token and is prepared to handle cancellation. Passing the `cancellationToken` object to this method simply allows the wait to be canceled. - -## Examples - The following example illustrates the simple use of a cancellation token to cancel waiting for a task's completion. A task is launched, calls the method to cancel any of the token source's cancellation tokens, and then delays for five seconds. Note that the task itself has not been passed the cancellation token and is not cancelable. The application thread calls the task's method to wait for the task to complete, but the wait is canceled once the cancellation token is cancelled and an is thrown. The exception handler reports the exception and then sleeps for six seconds. As the output from the example shows, that delay allows the task to complete in the state. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait3.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait3.vb" id="Snippet3"::: - + method creates a cancelable wait; that is, it causes the current thread to wait until one of the following occurs: + +- The task completes. + +- The cancellation token is canceled. In this case, the call to the method throws an . + +> [!NOTE] +> Canceling the `cancellationToken` cancellation token has no effect on the running task unless it has also been passed the cancellation token and is prepared to handle cancellation. Passing the `cancellationToken` object to this method simply allows the wait to be canceled. + +## Examples + The following example illustrates the simple use of a cancellation token to cancel waiting for a task's completion. A task is launched, calls the method to cancel any of the token source's cancellation tokens, and then delays for five seconds. Note that the task itself has not been passed the cancellation token and is not cancelable. The application thread calls the task's method to wait for the task to complete, but the wait is canceled once the cancellation token is cancelled and an is thrown. The exception handler reports the exception and then sleeps for six seconds. As the output from the example shows, that delay allows the task to complete in the state. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait3.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait3.vb" id="Snippet3"::: + ]]> The was canceled. The task has been disposed. - The task was canceled. The collection contains a object. - - -or- - + The task was canceled. The collection contains a object. + + -or- + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. @@ -5200,39 +5200,39 @@ This member is an explicit interface member implementation. It can be used only if the completed execution within the allotted time; otherwise, . - is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: - -- The task completes successfully. - -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - -- The interval defined by `timeout` elapses. In this case, the current thread resumes execution and the method returns `false`. - - - -## Examples - The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/Wait6.cs" id="Snippet6"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/Wait6.fs" id="Snippet6"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/Wait6.vb" id="Snippet6"::: - + is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: + +- The task completes successfully. + +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. + +- The interval defined by `timeout` elapses. In this case, the current thread resumes execution and the method returns `false`. + + + +## Examples + The following example starts a task that generates five million random integers between 0 and 100 and computes their mean. The example uses the method to wait for the application to complete within 150 milliseconds. If the application completes normally, the task displays the sum and mean of the random numbers that it has generated. If the timeout interval has elapsed, the example displays a message before it terminates. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/Wait6.cs" id="Snippet6"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/Wait6.fs" id="Snippet6"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/Wait6.vb" id="Snippet6"::: + ]]> The has been disposed. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. - The task was canceled. The collection contains a object. - - -or- - + The task was canceled. The collection contains a object. + + -or- + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. @@ -5284,43 +5284,43 @@ This member is an explicit interface member implementation. It can be used only if the completed execution within the allotted time; otherwise, . - is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: - -- The task completes successfully. - -- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. - -- The `cancellationToken` cancellation token is canceled. In this case, the call to the method throws an . - -- The interval defined by `millisecondsTimeout` elapses. In this case, the current thread resumes execution and the method returns `false`. - -> [!NOTE] -> Canceling the `cancellationToken` cancellation token has no effect on the running task unless it has also been passed the cancellation token and is prepared to handle cancellation. Passing the `cancellationToken` object to this method simply allows the wait to be canceled based on some condition. - - - -## Examples - The following example calls the method to provide both a timeout value and a cancellation token that can end the wait for a task's completion. A new thread is started and executes the `CancelToken` method, which pauses and then calls the method to cancel the cancellation tokens. A task is then launched and delays for 5 seconds. The method is then called to wait for the task's completion and is provided both a brief timeout value and a cancellation token. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait4.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait4.vb" id="Snippet4"::: - - Note that the precise output from the example depends on whether the wait was canceled because of the cancellation token or because the timeout interval elapsed. - + is a synchronization method that causes the calling thread to wait for the current task instance to complete until one of the following occurs: + +- The task completes successfully. + +- The task itself is canceled or throws an exception. In this case, you handle an exception. The property contains details about the exception or exceptions. + +- The `cancellationToken` cancellation token is canceled. In this case, the call to the method throws an . + +- The interval defined by `millisecondsTimeout` elapses. In this case, the current thread resumes execution and the method returns `false`. + +> [!NOTE] +> Canceling the `cancellationToken` cancellation token has no effect on the running task unless it has also been passed the cancellation token and is prepared to handle cancellation. Passing the `cancellationToken` object to this method simply allows the wait to be canceled based on some condition. + + + +## Examples + The following example calls the method to provide both a timeout value and a cancellation token that can end the wait for a task's completion. A new thread is started and executes the `CancelToken` method, which pauses and then calls the method to cancel the cancellation tokens. A task is then launched and delays for 5 seconds. The method is then called to wait for the task's completion and is provided both a brief timeout value and a cancellation token. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Wait/wait4.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Wait/wait4.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.wait/vb/wait4.vb" id="Snippet4"::: + + Note that the precise output from the example depends on whether the wait was canceled because of the cancellation token or because the timeout interval elapsed. + ]]> The was canceled. The has been disposed. is a negative number other than -1, which represents an infinite time-out. - The task was canceled. The collection contains a object. - - -or- - + The task was canceled. The collection contains a object. + + -or- + An exception was thrown during the execution of the task. The collection contains information about the exception or exceptions. @@ -5361,18 +5361,18 @@ This member is an explicit interface member implementation. It can be used only if the completed execution within the allotted time; otherwise, . To be added. - The was canceled - --or- - + The was canceled + +-or- + an exception was thrown during the execution of the . - is a negative number other than -1 milliseconds, which represents an - infinite time-out - --or- - -timeout is greater than + is a negative number other than -1 milliseconds, which represents an + infinite time-out + +-or- + +timeout is greater than . The was canceled. @@ -5444,24 +5444,24 @@ timeout is greater than An array of instances on which to wait. Waits for all of the provided objects to complete execution. - method wraps all exceptions in an object and propagates it to the calling thread. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/waitall.cs" id="Snippet02"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/waitall.fs" id="Snippet02"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/waitall.vb" id="Snippet02"::: - + method wraps all exceptions in an object and propagates it to the calling thread. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/Overview/waitall.cs" id="Snippet02"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/Overview/waitall.fs" id="Snippet02"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task/vb/waitall.vb" id="Snippet02"::: + ]]> One or more of the objects in has been disposed. The argument is . The argument contains a null element. - At least one of the instances was canceled. If a task was canceled, the exception contains an exception in its collection. - - -or- - + At least one of the instances was canceled. If a task was canceled, the exception contains an exception in its collection. + + -or- + An exception was thrown during the execution of at least one of the instances. @@ -5521,10 +5521,10 @@ timeout is greater than To be added. One or more of the objects in has been disposed. The argument is . - At least one of the instances was canceled. If a task was canceled, the contains an in its collection. - - -or- - + At least one of the instances was canceled. If a task was canceled, the contains an in its collection. + + -or- + An exception was thrown during the execution of at least one of the instances. is a negative number other than -1, which represents an infinite time-out. @@ -5583,19 +5583,19 @@ timeout is greater than A to observe while waiting for the tasks to complete. Waits for all of the provided objects to complete execution unless the wait is cancelled. - as noted above. - + as noted above. + ]]> The was canceled. The argument is . - At least one of the instances was canceled. If a task was canceled, the contains an in its collection. - - -or- - + At least one of the instances was canceled. If a task was canceled, the contains an in its collection. + + -or- + An exception was thrown during the execution of at least one of the instances. The argument contains a null element. One or more of the objects in has been disposed. @@ -5657,16 +5657,16 @@ timeout is greater than To be added. One or more of the objects in has been disposed. The argument is . - At least one of the instances was canceled. If a task was canceled, the contains an in its collection. - - -or- - + At least one of the instances was canceled. If a task was canceled, the contains an in its collection. + + -or- + An exception was thrown during the execution of at least one of the instances. - is a negative number other than -1 milliseconds, which represents an infinite time-out. - - -or- - + is a negative number other than -1 milliseconds, which represents an infinite time-out. + + -or- + is greater than Int32.MaxValue. The argument contains a null element. @@ -5727,19 +5727,19 @@ timeout is greater than if all of the instances completed execution within the allotted time; otherwise, . - noted above. - + noted above. + ]]> One or more of the objects in has been disposed. The argument is . - At least one of the instances was canceled. If a task was canceled, the contains an in its collection. - - -or- - + At least one of the instances was canceled. If a task was canceled, the contains an in its collection. + + -or- + An exception was thrown during the execution of at least one of the instances. is a negative number other than -1, which represents an infinite time-out. @@ -5809,15 +5809,15 @@ timeout is greater than Waits for any of the provided objects to complete execution. The index of the completed object in the array. - method then waits for any of the tasks to complete. The example displays the task ID of the task that ended the wait, as well as the current status of all the tasks. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WaitAny/WaitAny1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WaitAny/WaitAny1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Threading.Tasks.Task.WaitAny/vb/WaitAny1.vb" id="Snippet1"::: - + method then waits for any of the tasks to complete. The example displays the task ID of the task that ended the wait, as well as the current status of all the tasks. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WaitAny/WaitAny1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WaitAny/WaitAny1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/System.Threading.Tasks.Task.WaitAny/vb/WaitAny1.vb" id="Snippet1"::: + ]]> The has been disposed. @@ -5981,10 +5981,10 @@ timeout is greater than To be added. The has been disposed. The argument is . - The property of the argument is a negative number other than -1, which represents an infinite time-out. - - -or- - + The property of the argument is a negative number other than -1, which represents an infinite time-out. + + -or- + The property of the argument is greater than Int32.MaxValue. The argument contains a null element. @@ -6295,31 +6295,31 @@ timeout is greater than Creates a task that will complete when all of the objects in an enumerable collection have completed. A task that represents the completion of all of the supplied tasks. - method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. - -> [!NOTE] -> The call to method does not block the calling thread. - - If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. - - If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. - - If the supplied array/enumerable contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. - - - -## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.cs" id="Snippet4"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.fs" id="Snippet4"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/WhenAll4.vb" id="Snippet4"::: - + method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. + +> [!NOTE] +> The call to method does not block the calling thread. + + If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. + + If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. + + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. + + If the supplied array/enumerable contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. + + + +## Examples + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.cs" id="Snippet4"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll4.fs" id="Snippet4"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/WhenAll4.vb" id="Snippet4"::: + ]]> The argument was . @@ -6378,31 +6378,31 @@ timeout is greater than Creates a task that will complete when all of the objects in an array have completed. A task that represents the completion of all of the supplied tasks. - method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. - -> [!NOTE] -> The call to method does not block the calling thread. - - If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. - - If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. - - If the supplied array/enumerable contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. - - - -## Examples - The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.cs" id="Snippet3"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.fs" id="Snippet3"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/WhenAll3.vb" id="Snippet3"::: - + method that return a object are typically called when you are interested in the status of a set of tasks or in the exceptions thrown by a set of tasks. + +> [!NOTE] +> The call to method does not block the calling thread. + + If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. + + If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. + + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. + + If the supplied array/enumerable contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. + + + +## Examples + The following example creates a set of tasks that ping the URLs in an array. The tasks are stored in a `List` collection that is converted to an array and passed to the method. After the call to the method ensures that all threads have completed, the example examines the property to determine whether any tasks have faulted. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.cs" id="Snippet3"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/WhenAll3.fs" id="Snippet3"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/WhenAll3.vb" id="Snippet3"::: + ]]> The argument was . @@ -6465,30 +6465,30 @@ timeout is greater than Creates a task that will complete when all of the objects in an enumerable collection have completed. A task that represents the completion of all of the supplied tasks. - method does not block the calling thread. However, a call to the returned property does block the calling thread. - - If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. - - If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. - - If the `tasks` argument contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. - - - -## Examples - The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/whenall1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/whenall1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/whenall1.vb" id="Snippet1"::: - - In this case, the ten individual tasks are stored in a object. implements the interface. - + method does not block the calling thread. However, a call to the returned property does block the calling thread. + + If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. + + If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. + + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The property of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's property will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. + + If the `tasks` argument contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. + + + +## Examples + The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/whenall1.cs" id="Snippet1"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/whenall1.fs" id="Snippet1"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/whenall1.vb" id="Snippet1"::: + + In this case, the ten individual tasks are stored in a object. implements the interface. + ]]> The argument was . @@ -6558,28 +6558,28 @@ timeout is greater than Creates a task that will complete when all of the objects in an array have completed. A task that represents the completion of all of the supplied tasks. - method does not block the calling thread. However, a call to the returned property does block the calling thread. - - If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. - - If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. - - If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. - - If the supplied array/enumerable contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. - - - -## Examples - The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. In this case, the ten individual tasks are stored in a `Task` array. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. - - :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/whenall2.cs" id="Snippet2"::: - :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/whenall2.fs" id="Snippet2"::: - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/whenall2.vb" id="Snippet2"::: - + method does not block the calling thread. However, a call to the returned property does block the calling thread. + + If any of the supplied tasks completes in a faulted state, the returned task will also complete in a state, where its exceptions will contain the aggregation of the set of unwrapped exceptions from each of the supplied tasks. + + If none of the supplied tasks faulted but at least one of them was canceled, the returned task will end in the state. + + If none of the tasks faulted and none of the tasks were canceled, the resulting task will end in the state. The of the returned task will be set to an array containing all of the results of the supplied tasks in the same order as they were provided (e.g. if the input tasks array contained t1, t2, t3, the output task's will return an `TResult[]` where `arr[0] == t1.Result, arr[1] == t2.Result, and arr[2] == t3.Result)`. + + If the supplied array/enumerable contains no tasks, the returned task will immediately transition to a state before it's returned to the caller. The returned `TResult[]` will be an array of 0 elements. + + + +## Examples + The following example creates ten tasks, each of which instantiates a random number generator that creates 1,000 random numbers between 1 and 1,000 and computes their mean. In this case, the ten individual tasks are stored in a `Task` array. The method is used to delay instantiation of the random number generators so that they are not created with identical seed values. The call to the method then returns an array that contains the mean computed by each task. These are then used to calculate the overall mean. + + :::code language="csharp" source="~/snippets/csharp/System.Threading.Tasks/Task/WhenAll/whenall2.cs" id="Snippet2"::: + :::code language="fsharp" source="~/snippets/fsharp/System.Threading.Tasks/Task/WhenAll/whenall2.fs" id="Snippet2"::: + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.tasks.task.whenall/vb/whenall2.vb" id="Snippet2"::: + ]]> The argument was . @@ -6641,11 +6641,11 @@ timeout is greater than Creates a task that will complete when any of the supplied tasks have completed. A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - The argument was . @@ -6704,11 +6704,11 @@ timeout is greater than Creates a task that will complete when any of the supplied tasks have completed. A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - The argument was null. @@ -6753,12 +6753,12 @@ timeout is greater than Creates a task that will complete when either of the supplied tasks have completed. A new task that represents the completion of one of the supplied tasks. Its is the task that completed first. - @@ -6821,11 +6821,11 @@ The returned task will complete when any of the supplied tasks has completed. T Creates a task that will complete when any of the supplied tasks have completed. A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - The argument was . @@ -6895,11 +6895,11 @@ The returned task will complete when any of the supplied tasks has completed. T Creates a task that will complete when any of the supplied tasks have completed. A task that represents the completion of one of the supplied tasks. The return task's Result is the task that completed. - The argument was null. @@ -6955,15 +6955,15 @@ The returned task will complete when any of the supplied tasks has completed. T Creates a task that will complete when either of the supplied tasks have completed. A task that represents the completion of one of the supplied tasks. The returned task's is the task that completed first. - [!TIP] -> In every overloaded version of Task.WhenAny() when this method returns the first completed task, the other tasks will continue running until completion, even any of them completed in the `Canceled` or `Faulted` state. So, if that behavior is not desired you may want to cancel all the remaining tasks once the first task complete. - + [!TIP] +> In every overloaded version of Task.WhenAny() when this method returns the first completed task, the other tasks will continue running until completion, even any of them completed in the `Canceled` or `Faulted` state. So, if that behavior is not desired you may want to cancel all the remaining tasks once the first task complete. + ]]> @@ -7012,11 +7012,11 @@ The returned task will complete when any of the supplied tasks has completed. T Creates an awaitable task that asynchronously yields back to the current context when awaited. A context that, when awaited, will asynchronously transition back into the current context at the time of the await. If the current is non-null, it is treated as the current context. Otherwise, the task scheduler that is associated with the currently executing task is treated as the current context. - object), this will post the remainder of the method's execution back to that context. However, the context will decide how to prioritize this work relative to other work that may be pending. The synchronization context that is present on a UI thread in most UI environments will often prioritize work posted to the context higher than input and rendering work. For this reason, do not rely on `await Task.Yield();` to keep a UI responsive. For more information, see the entry [Useful Abstractions Enabled with ContinueWith](https://devblogs.microsoft.com/pfxteam/useful-abstractions-enabled-with-continuewith/) in the Parallel Programming with .NET blog. - + object), this will post the remainder of the method's execution back to that context. However, the context will decide how to prioritize this work relative to other work that may be pending. The synchronization context that is present on a UI thread in most UI environments will often prioritize work posted to the context higher than input and rendering work. For this reason, do not rely on `await Task.Yield();` to keep a UI responsive. For more information, see the entry [Useful Abstractions Enabled with ContinueWith](https://devblogs.microsoft.com/pfxteam/useful-abstractions-enabled-with-continuewith/) in the Parallel Programming with .NET blog. + ]]>