From 78845debcecd0ac8fad59dd3cf88c4ef97882ff9 Mon Sep 17 00:00:00 2001 From: Edward Brey Date: Sun, 17 May 2020 14:17:08 -0500 Subject: [PATCH 1/7] Clarify scope of cancelation in Task.Run Task.Run accepts a cancellation token, but doesn't provide it to the invoked method. The cancellation token is only used to cancel the action if it has not started running. This edit corrects the following problems: * Summary sentence about cancelation didn't indicate that it only applies before the action starts running. * Summary sentence was inconsistently present across the various Run overloads. * The `cancelationToken` parameter offered inconsistent guidance. * The `cancelationToken` parameter for one overload said it "should" be provided. This is often poor guidance. In systems were the thread utilization is low, the action will start immediately, and there is no point in providing a cancellation token. It is often useful to provide a cancellation token to the action, but that's not what the `cancelationToken` parameter in `Run` does. Further updates to the docs to clarify this may be helpful. --- xml/System.Threading.Tasks/Task.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 113721c1f93..b322b3e4dd4 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3425,8 +3425,8 @@ Task t Status: RanToCompletion, Result: 42 The work to execute asynchronously - A cancellation token that can be used to cancel the work - 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. + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + 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. The work to execute asynchronously. - A cancellation token that should be used to cancel the work. - Queues the specified work to run on the thread pool and returns a proxy for the task returned by . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + 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 type of the result returned by the proxy task. The work to execute asynchronously - Queues the specified work to run on the thread pool and returns a proxy for the returned by . + 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 return type of the task. The work to execute asynchronously. - Queues the specified work to run on the thread pool and returns a object that represents that work. + 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. The type of the result returned by the proxy task. The work to execute asynchronously - A cancellation token that should be used to cancel the work + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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 . @@ -3749,8 +3749,8 @@ Task t Status: RanToCompletion, Result: 42 The result type of the task. The work to execute asynchronously - A cancellation token that should be used to cancel the work - 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. + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + 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. Date: Wed, 10 Jun 2020 07:18:01 -0500 Subject: [PATCH 2/7] Update xml/System.Threading.Tasks/Task.xml Co-authored-by: Maira Wenzel --- xml/System.Threading.Tasks/Task.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index b322b3e4dd4..d4b64f529bd 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3425,7 +3425,7 @@ Task t Status: RanToCompletion, Result: 42 The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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. From 066fe9627db344f293a2ed5b94a600a77c3dea6b Mon Sep 17 00:00:00 2001 From: Edward Brey Date: Wed, 10 Jun 2020 07:18:17 -0500 Subject: [PATCH 3/7] Update xml/System.Threading.Tasks/Task.xml Co-authored-by: Maira Wenzel --- xml/System.Threading.Tasks/Task.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index d4b64f529bd..a1a5e9b8a54 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3497,7 +3497,7 @@ Task t Status: RanToCompletion, Result: 42 The work to execute asynchronously. - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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 . From 4e62702eaa468e1c5332fc4752aed6c13452134a Mon Sep 17 00:00:00 2001 From: Edward Brey Date: Wed, 10 Jun 2020 07:18:29 -0500 Subject: [PATCH 4/7] Update xml/System.Threading.Tasks/Task.xml Co-authored-by: Maira Wenzel --- xml/System.Threading.Tasks/Task.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index a1a5e9b8a54..27d7f6b5e86 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3688,7 +3688,7 @@ Task t Status: RanToCompletion, Result: 42 The type of the result returned by the proxy task. The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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 . From 8244d16e6cd3d854df6d4dc68a2558d00446a755 Mon Sep 17 00:00:00 2001 From: Edward Brey Date: Wed, 10 Jun 2020 07:18:38 -0500 Subject: [PATCH 5/7] Update xml/System.Threading.Tasks/Task.xml Co-authored-by: Maira Wenzel --- xml/System.Threading.Tasks/Task.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 27d7f6b5e86..aa2f8817a67 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3749,7 +3749,7 @@ Task t Status: RanToCompletion, Result: 42 The result type of the task. The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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. From 97ea62f966e2d60ab746a41e4c766c56b24a08e2 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Mon, 22 Jun 2020 12:12:45 -0700 Subject: [PATCH 6/7] Apply suggestions from code review --- xml/System.Threading.Tasks/Task.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index aa2f8817a67..0bb34b73ec6 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3425,7 +3425,7 @@ Task t Status: RanToCompletion, Result: 42 The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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. @@ -3497,7 +3497,7 @@ Task t Status: RanToCompletion, Result: 42 The work to execute asynchronously. - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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 . @@ -3688,7 +3688,7 @@ Task t Status: RanToCompletion, Result: 42 The type of the result returned by the proxy task. The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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 . @@ -3749,7 +3749,7 @@ Task t Status: RanToCompletion, Result: 42 The result type of the task. The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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. From a412ea456c72352cdde0f8d101e0079f552359fa Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Tue, 21 Jul 2020 14:39:46 -0700 Subject: [PATCH 7/7] Fix build warnings for crefs. --- xml/System.Threading.Tasks/Task.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml index 0bb34b73ec6..1dbf4763b5d 100644 --- a/xml/System.Threading.Tasks/Task.xml +++ b/xml/System.Threading.Tasks/Task.xml @@ -3425,7 +3425,7 @@ Task t Status: RanToCompletion, Result: 42 The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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. @@ -3497,7 +3497,7 @@ Task t Status: RanToCompletion, Result: 42 The work to execute asynchronously. - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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 . @@ -3688,7 +3688,7 @@ Task t Status: RanToCompletion, Result: 42 The type of the result returned by the proxy task. The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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 . @@ -3749,7 +3749,7 @@ Task t Status: RanToCompletion, Result: 42 The result type of the task. The work to execute asynchronously - A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . + A cancellation token that can be used to cancel the work if it has not yet started. does not pass to . 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.