From 5a2b5668325642bf261a782a17d9b74409a84128 Mon Sep 17 00:00:00 2001 From: Smaug123 <3138005+Smaug123@users.noreply.github.com> Date: Tue, 18 Mar 2025 20:01:21 +0000 Subject: [PATCH 1/3] Explain semantics of multiple calls to `CancellationTokenSource.Cancel` Also copy a line about LIFO semantics from one of the overloads, to unify the docs for each function. --- xml/System.Threading/CancellationTokenSource.xml | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index 1148c15c046..23006112346 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -383,8 +383,10 @@ ## Remarks The associated will be notified of the cancellation and will transition to a state where returns true. - Any callbacks or cancelable operations registered with the will be executed. - + Any callbacks or cancelable operations registered with the will be executed, if they have not already been executed by a previous call to . Subsequent calls to will not execute the same callback again unless re-registered. (We recommend avoiding multiple calls to , because the intent of such code is often unclear.) + + Callbacks will be executed synchronously in LIFO order. + We recommend that cancelable operations and callbacks registered with not throw exceptions. This overload of Cancel will aggregate any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. @@ -458,7 +460,9 @@ ## Remarks The associated will be notified of the cancellation and will transition to a state where returns `true`. - Any callbacks or cancelable operations registered with the will be executed. Callbacks will be executed synchronously in LIFO order. + Any callbacks or cancelable operations registered with the will be executed, if they have not already been executed by a previous call to . Subsequent calls to will not execute the same callback again unless re-registered. (We recommend avoiding multiple calls to , because the intent of such code is often unclear.) + + Callbacks will be executed synchronously in LIFO order. We recommend that cancelable operations and callbacks registered with not throw exceptions. From 45f918e1ff1c2a9d206de20118fc85cf2f5cf6a4 Mon Sep 17 00:00:00 2001 From: Smaug123 <3138005+Smaug123@users.noreply.github.com> Date: Tue, 25 Mar 2025 20:27:18 +0000 Subject: [PATCH 2/3] 'will be notified' -> 'is notified' --- xml/System.Threading/CancellationTokenSource.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index 23006112346..3bcd62e6adc 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -381,7 +381,7 @@ will be notified of the cancellation and will transition to a state where returns true. + The associated is notified of the cancellation and transitions to a state where returns true. Any callbacks or cancelable operations registered with the will be executed, if they have not already been executed by a previous call to . Subsequent calls to will not execute the same callback again unless re-registered. (We recommend avoiding multiple calls to , because the intent of such code is often unclear.) @@ -458,7 +458,7 @@ will be notified of the cancellation and will transition to a state where returns `true`. + The associated is notified of the cancellation and transitions to a state where returns `true`. Any callbacks or cancelable operations registered with the will be executed, if they have not already been executed by a previous call to . Subsequent calls to will not execute the same callback again unless re-registered. (We recommend avoiding multiple calls to , because the intent of such code is often unclear.) @@ -636,8 +636,8 @@ Communicates a request for cancellation asynchronously. A task that will complete after cancelable operations and callbacks registered with the associated have completed. - The associated will be notified of the cancellation and will synchronously transition to a state where returns . - Any callbacks or cancelable operations registered with the will be executed asynchronously, with the returned representing their eventual completion. + The associated is notified of the cancellation and synchronously transitions to a state where returns . + Any callbacks or cancelable operations registered with the will be executed asynchronously, with the returned representing their eventual completion. Callbacks registered with the token should not throw exceptions. However, any such exceptions that are thrown will be aggregated into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. From 8094c7a591d6a27e2d49611edc2cbdf675d4ba70 Mon Sep 17 00:00:00 2001 From: Smaug123 <3138005+Smaug123@users.noreply.github.com> Date: Tue, 25 Mar 2025 20:35:01 +0000 Subject: [PATCH 3/3] Consistently use the present tense --- xml/System.Threading/CancellationTokenSource.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/xml/System.Threading/CancellationTokenSource.xml b/xml/System.Threading/CancellationTokenSource.xml index 3bcd62e6adc..fd047fb2840 100644 --- a/xml/System.Threading/CancellationTokenSource.xml +++ b/xml/System.Threading/CancellationTokenSource.xml @@ -383,13 +383,13 @@ ## Remarks The associated is notified of the cancellation and transitions to a state where returns true. - Any callbacks or cancelable operations registered with the will be executed, if they have not already been executed by a previous call to . Subsequent calls to will not execute the same callback again unless re-registered. (We recommend avoiding multiple calls to , because the intent of such code is often unclear.) + Any callbacks or cancelable operations registered with the are executed, if they haven't already been executed by a previous call to . Subsequent calls to won't execute the same callback again unless reregistered. (Avoid multiple calls to , because the intent of such code is often unclear.) - Callbacks will be executed synchronously in LIFO order. + Callbacks are executed synchronously in LIFO order. We recommend that cancelable operations and callbacks registered with not throw exceptions. - This overload of Cancel will aggregate any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. + This overload of Cancel aggregates any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. Calling this method has the same effect as calling [`Cancel(false)`](xref:System.Threading.CancellationTokenSource.Cancel(System.Boolean)). @@ -460,15 +460,15 @@ ## Remarks The associated is notified of the cancellation and transitions to a state where returns `true`. - Any callbacks or cancelable operations registered with the will be executed, if they have not already been executed by a previous call to . Subsequent calls to will not execute the same callback again unless re-registered. (We recommend avoiding multiple calls to , because the intent of such code is often unclear.) + Any callbacks or cancelable operations registered with the are executed, if they haven't already been executed by a previous call to . Subsequent calls to won't execute the same callback again unless reregistered. (Avoid multiple calls to , because the intent of such code is often unclear.) - Callbacks will be executed synchronously in LIFO order. + Callbacks are executed synchronously in LIFO order. We recommend that cancelable operations and callbacks registered with not throw exceptions. If `throwOnFirstException` is `true`, an exception will immediately propagate out of the call to , preventing the remaining callbacks and cancelable operations from being processed. - If `throwOnFirstException` is `false`, this overload will aggregate any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. + If `throwOnFirstException` is `false`, this overload aggregates any exceptions thrown into an , such that one callback throwing an exception will not prevent other registered callbacks from being executed. ]]>