Task cancellation in C# and things you should know about it

refs:

https://binary-studio.com/2015/10/23/task-cancellation-in-c-and-things-you-should-know-about-it/

Task mechanism in C# is a powerful beast in the area of parallel and asynchrony programming. Controlling this beast may take lots of efforts and pain. .NET Framework 4 introduces a convenient approach for cancellation of asynchronous operations.

How do we control

Why should we control execution flow of the tasks? One reason is business logic or algorithm requirements. Another reason comes from an idea, that there should be no unobserved tasks. Such tasks may hold thread pool and CPU resources and therefore be dangerous.

Just for this .NET provides us with two classes:

• CancellationTokenSource – object responsible for creating cancellation token and sending cancellation request to all copies of that token.
• CancellationToken – structure used by listeners to monitor token current state.

How do we pass token

Firstly, we should somehow make task use created token. One way is to pass it as an argument to the method responsible for creating task.

CancellationTokenSource tokenSource = newCancellationTokenSource(); CancellationToken token = tokenSource.Token; tokenSource.Cancel(); Task.Run(() => Console.WriteLine("Hello from Task"), token);

1 2 3 4

CancellationTokenSource tokenSource = newCancellationTokenSource ( ) ; CancellationToken token = tokenSource . Token ; tokenSource . Cancel ( ) ; Task . Run ( ( ) = > Console . WriteLine ( "Hello from Task" ) , token ) ;

With such approach token is only checked at the very beginning, before starting execution of task delegate code. If token cancelled then task is also put in canceled mode. In the example above message won’t be printed because token had been canceled before task were created.

But what if we want to stop task execution in particular moment of time? Then you should observe cancellation token state manually inside task delegate. There are generally two ways for passing token inside task delegate.

First way is to make token variable visible by task delegate. It can be accomplished by using global variable or variable capture.

var token = tokenSource.Token; Task.Run(() => { var capturedToken = token; ... }, token);

1 2 3 4 5 6 7

var token = tokenSource . Token ;   Task . Run ( ( ) = > {      var capturedToken = token ;      . . . } , token ) ;

Second way is to pass token as state object and downcast it inside task delegate.

var token = tokenSource.Token; Task.Factory.StartNew(stateObject => { var castedToken = (CancellationToken) stateObject; ... }, token, token);

1 2 3 4 5 6 7 8

var token = tokenSource . Token ;   Task . Factory . StartNew ( stateObject = > {        var castedToken = ( CancellationToken ) stateObject ;      . . . } , token , token ) ;

How do we observe token

Now that we know how to access token inside a task, it is time to become acquainted with how we can observe token state. You can observe it in the three ways: by polling, using callback registration and via wait handle.

1. By polling – periodically check IsCancellationRequested property

Task.Run(() => { //Polling boolean property while (!token.IsCancellationRequested) { //Do some work } //Release resources and exit }, token);

1 2 3 4 5 6 7 8

Task . Run ( ( ) = > {      //Polling boolean property      while ( ! token . IsCancellationRequested ) {          //Do some work      }      //Release resources and exit } , token ) ;

2. Callback registration – provide callback that would be executed right after cancellation is requested

Task.Run(async () => { var webClient = newWebClient(); //Registering callback that would cancel downloading token.Register(() => webClient.CancelAsync()); var data = await webClient.DownloadDataTaskAsync("http://www.google.com/"); }, token);

1 2 3 4 5 6 7

Task . Run ( async ( ) = > {      var webClient = newWebClient ( ) ;      //Registering callback that would cancel downloading      token . Register ( ( ) = > webClient . CancelAsync ( ) ) ;      var data = await webClient . DownloadDataTaskAsync ( "http://www.google.com/" ) ; } , token ) ;

3. Waiting for wait handle provided by CancellationToken.

var autoResetEvent = newAutoResetEvent(false); //Some code... Task.Run(() => { var handleArray = new[] {autoResetEvent, token.WaitHandle}; //Waiting on wait handle to signal first var finishedId = WaitHandle.WaitAny(handleArray); if (finishedId == Array.IndexOf(handleArray, token.WaitHandle)){ //If token wait handle was first to signal then exit return; } //Continue working... }, token);

1 2 3 4 5 6 7 8 9 10 11 12 13

var autoResetEvent = newAutoResetEvent ( false ) ; //Some code... Task . Run ( ( ) = > {      var handleArray = new [ ] { autoResetEvent , token . WaitHandle } ;      //Waiting on wait handle to signal first      var finishedId = WaitHandle . WaitAny ( handleArray ) ;      if ( finishedId == Array . IndexOf ( handleArray , token . WaitHandle ) ) {          //If token wait handle was first to signal then exit          return ;      }      //Continue working... } , token ) ;

You can also observe multiple tokens simultaneously, by creating linked token source that can join multiple tokens into one.

CancellationTokenSource linkedToukenSource = CancellationTokenSource.CreateLinkedTokenSource(firstToken, secondToken); CancellationToken lindkedToken = linkedToukenSource.Token;

1 2 3

CancellationTokenSource linkedToukenSource = CancellationTokenSource . CreateLinkedTokenSource ( firstToken , secondToken ) ;   CancellationToken lindkedToken = linkedToukenSource . Token ;

How do we cancel

We already know how to pass and observe tokens. What is left is how we send cancellation request. For cancelling, we use CancellationTokenSource object. Cancellation request may be direct or deferred.

//#1 Request cancellation after timeoutvar tokenSource = newCancellationTokenSource(TimeSpan.FromSeconds(2)); //#2 Request cancellation after timeout tokenSource.CancelAfter(TimeSpan.FromSeconds(2)); //#3 Directly request cancellation tokenSource.Cancel(); //or tokenSource.Cancel(true);

1 2 3 4 5 6 7 8 9 10 11

//#1 Request cancellation after timeoutvar tokenSource = newCancellationTokenSource ( TimeSpan . FromSeconds ( 2 ) ) ;   //#2 Request cancellation after timeout tokenSource . CancelAfter ( TimeSpan . FromSeconds ( 2 ) ) ;   //#3 Directly request cancellation tokenSource . Cancel ( ) ;   //or tokenSource . Cancel ( true ) ;

When we use Cancel method directly, it implicitly calls all registered callbacks on current thread. If callbacks throw exceptions, they are wrapped in AggregateException object that propagated then to caller.

Since callbacks is called one by one, optional boolean argument for Cancel method lets you specify behavior upon encountering exception in any of the registered callbacks.

If argument is true then exception will immediately propagate out of the call to Cancel, preventing the remaining callbacks from executing.

If argument is false, all registered callbacks will be executed with all thrown exceptions wrapped into the AggregateException.

After detecting cancellation request inside task, common approach is to throw OperationCanceledException object, to put task in canceled state.

Task.Run(() => { while (true) { //Do some work if (token.IsCancellationRequested) { token.ThrowIfCancellationRequested(); } } }, token);

1 2 3 4 5 6 7 8 9 10 11

Task . Run ( ( ) = > {    while ( true )    {      //Do some work      if ( token . IsCancellationRequested )      {          token . ThrowIfCancellationRequested ( ) ;      }      } } , token ) ;

Conclusion

Task cancellation mechanism is an easy and useful tool for controlling task execution flow. It is a part of big .NET Framework ecosystem, therefore its usage in most cases is more preferable than some custom solutions.