The orderly shutdown of threads in a multithreaded application is an important task to ensure proper disposal of resources and completion of work items without losing data. This is usually handled by setting a shared variable to a signaled value for the thread(s) to monitor, or in extreme cases through the use of Thread.Abort method. Either of these are problematic to control and ensure proper operation, especially as the # of threads gets to be over one! And even still, the process of determining when all threads have stopped also is wrought with problems.
To alleviate these problems, the TPL provides a new mechanism for controlling the shutdown of tasks, referred to a CancellationToken. CancellationToken’s provide a model of cooperative shutdown of tasks, where cancellation tokens provide a well defined means of being able to signal task cancellation, and to also provide information to the signaler that all tasks have indeed shutdown.
Additionally, TPL tasks may not even be implemented by threads, and therefore a new mechanism is required. It is currently the case that tasks are implemented on the thread pool, but other task factories can be implemented to schedule code execution in other means, for example on the GPU which would not use the normal threading API’s. The cancellation token model then also provides a unified cancellation model that can work with multiple task implemenations, as well as coordinating shutdown of tasks running in different implementations.
Understanding of the different patterns of implementing shutdown is important to being able to interoperate successfully in a coordinated model of cancellation. As a general practice, you should not assume that your task works in isolation, that it may need to be cancelled in combination to other tasks upon the request of a supervisory task. And your task should be implemented in a means that they can always identify and cancel operation in a timely manner.
To be a good citizen of TPL, task implementations and coordination should follow a number of patterns, all of which have slightly different ramifications on how orchestration of cancellation occurs. This is the purpose of this sequence of posts, to introduce the reader to these different patterns.
The first pattern we'll examine I refer to as "cancellation via polling". The following code exemplifies the pattern. A function is declared that will run run as a task. One of the parameters to the function will be a CancellationToken, which the implementation of the function can use to identify that a cancellation has been signaled. The function in this examples continuously loops, with each loop pausing for 100ms to simulate some work, and incrementing a count through each iteration. When cancellation is identified, the function will return the number of iterations performed.
var f = new Func(
(token) =>
{
var count = 0;
while (!token.IsCancellationRequested)
{
count++;
Task.Delay(100).Wait();
}
return count;
}
);
var cts = new CancellationTokenSource();
var ct = cts.Token;
var task = Task.Factory.StartNew(() => f(ct));
Task.Delay(500).Wait();
cts.Cancel();
task.Wait();
Console.WriteLine("{0}", task.Status);
if (task.Status == TaskStatus.RanToCompletion) Console.WriteLine("{0}", task.Result);
Cancellation tokens are not directly instantiated. Instead they are created via a factory class called CancellationTokenSource. The actual token is available via the CancellationTokenSource's Token property. The token is then passed to methods to track signaling of cancellation via the tokens IsCancellationRequested property. The actual signal for cancellation is set on the cancellation token source, not on the token. Also, you can only signal cancellation once, and you can't reverse a cancellation request.
This example creates a cancellation token, and then runs the method as a task and passes the cancellation token to the task. It then delays for 500ms, which gives the task time to do roughly 5 iterations. After this short delay, the cancellation token is signaled via the Cancel method of the token source, which will cause the task to see the signal during its next iteration, which in this case may take up to 100ms. Note that setting the cancellation does not terminate / abort any tasks, it is just setting a value that all tasks that have been passed this token can identify.
After setting the cancellation signal, this code then waits for the task to complete. If the task is implemented to work well with collaborative cancellation, then the task will complete work and move into a state that the wait method on the task will eventually, and if done correctly, complete in a timely manner. In this example, this could take upwards to 100ms.
The example then writes to the console the value of the state of the task, and then the Result property of the task. The output from this example should be the following (perhaps a slight variance in the count due to processor differences).
RanToCompletion
5
Press any key to continue . . .
This is the result that was expected. While the main thread/task waits for 500ms, the sub-task will iterate five times, see the signal, exit the while loop, and then return the value. The task will notice the method call completing, and transition to the RanToCompletion state.
This example does exhibit a problem: the fact that it may take 100ms for the signal to be identified. This can be rectified by passing the token to the Task.Delay method (modified method shown):
var f = new Func(
(token) =>
{
var count = 0;
while (!token.IsCancellationRequested)
{
count++;
Task.Delay(100, token).Wait();
}
return count;
}
);
The Delay method will then watch the cancellation token for it's signal, and return immediately upon recognition. When running, the output is then:
Unhandled Exception: System.AggregateException: One or more errors occurred. ---> System.AggregateException: One or more
errors occurred. ---> System.Threading.Tasks.TaskCanceledException: A task was canceled.
--- End of inner exception stack trace ---
at System.Threading.Tasks.Task.ThrowIfExceptional(Boolean includeTaskCanceledExceptions)
at System.Threading.Tasks.Task.Wait(Int32 millisecondsTimeout, CancellationToken cancellationToken)
Whoopsies! What's going on?
The answer is that it is, in many cases, considered proper form in processing a signal for cancellation to execute the ThrowIfCancellationRequested method of the cancellation token. This will throw a TaskCanceledException and exit the method. The Task.Delay method does just this. And since the code does not catch the exception, execution of the app completely aborts.
To handle the exception, there are three sub-patterns that you can follow. The first is to wrap the code starting the task that propagates the exception with a try/catch. A modification like this could look like the following:
try
{
cts.Cancel();
task.Wait();
}
catch (AggregateException ex)
{
Console.WriteLine(ex.Message);
Console.WriteLine(ex.InnerExceptions[0].InnerException.Message);
}
And the results would be the following:
One or more errors occurred.
A task was canceled.
Faulted
Press any key to continue . . .
The exception that is thrown in this case is actually an AggregateException. This is an exception class that wraps one or more other exceptions. Each task that executes the token's ThrowIfCancellationRequested method will have a TaskAbortedException object included as one of the InnerExceptions.
This pattern of aggregating exceptions like this is actually very convenient. It is a way of a task that has received the cancellation signal to notify the signaler that it has canceled effectively.
Let's look at how this can be used by modifying the example a little. The modification allows the passing in of the delay value to the method, and also has the method stop iterating / complete after 3 iterations. Two tasks are then started, one with a 100ms interval and the other with 250ms. The same delay of 500ms is performed, and then the cancel is signaled.
var f = new Func(
(interval, token) =>
{
var count = 0;
while (!token.IsCancellationRequested & count < 3)
{
count++;
Task.Delay(interval, token).Wait();
}
return count;
}
);
var cts = new CancellationTokenSource();
var ct = cts.Token;
var task1 = Task.Factory.StartNew(() => f(100, ct));
var task2 = Task.Factory.StartNew(() => f(250, ct));
Task.Delay(500).Wait();
try
{
cts.Cancel();
Task.WaitAll(task1, task2);
}
catch (AggregateException)
{
}
Console.WriteLine("task1.Status == {0}", task1.Status);
if (task1.Status == TaskStatus.RanToCompletion) Console.WriteLine("{0}", task1.Result);
Console.WriteLine("task2.Status == {0}", task2.Status);
if (task2.Status == TaskStatus.RanToCompletion) Console.WriteLine("{0}", task2.Result);
When executed, the following is the result:
task1.Status == RanToCompletion
3
task2.Status == Faulted
Press any key to continue . . .
The first task can complete 3 iterations within 500ms, and therefore moves to RanToCompletion status, and the second task does not, throws a TaskAbortedException, and moves to the Faulted state. The exception can then be used to identify which one of the tasks has not completed and responded to the cancellation request. Normally, a lot more work when using threads.
What if we wanted to see how many iterations were completed by a task before the cancel signal was identified? The method can be changed to catch the exception thrown by the Task.Delay task and exit normally, as follows:
var f = new Func(
(interval, token) =>
{
var count = 0;
while (!token.IsCancellationRequested & count < 3)
{
count++;
try
{
Task.Delay(interval, token).Wait();
}
catch (AggregateException)
{
}
}
return count;
}
);
var cts = new CancellationTokenSource();
var ct = cts.Token;
var task1 = Task.Factory.StartNew(() => f(100, ct));
var task2 = Task.Factory.StartNew(() => f(250, ct));
Task.Delay(500).Wait();
try
{
cts.Cancel();
Task.WaitAll(task1, task2);
}
catch (AggregateException)
{
}
Console.WriteLine("task1.Status == {0}", task1.Status);
if (task1.Status == TaskStatus.RanToCompletion) Console.WriteLine("{0}", task1.Result);
Console.WriteLine("task2.Status == {0}", task2.Status);
if (task2.Status == TaskStatus.RanToCompletion) Console.WriteLine("{0}", task2.Result);
And the results:
task1.Status == RanToCompletion
3
task2.Status == RanToCompletion
2
Press any key to continue . . .
Because the exception was caught in the task, and the method executed by the task completed, both now exit cleanly, no exceptions thrown, the state of both move to RanToCompletion, and the results from each retrieved.
Now as if these weren't enough permutations on how to do a cancellation, there are still more. We have not examined actually throwing a TaskAbortedException to get out of our task. Lets look at the following modification of the code.
var f = new Func(
(interval, token) =>
{
while (true)
{
Task.Delay(100).Wait();
token.ThrowIfCancellationRequested();
}
}
);
var cts = new CancellationTokenSource();
var ct = cts.Token;
var task1 = Task.Factory.StartNew(() => f(100, ct));
Task.Delay(500).Wait();
try
{
cts.Cancel();
task1.Wait();
}
catch (AggregateException ex)
{
Console.WriteLine("Caught exception {0}", ex.InnerExceptions[0].Message);
}
Console.WriteLine("task1.Status == {0}", task1.Status);
if (task1.Status == TaskStatus.RanToCompletion) Console.WriteLine("{0}", task1.Result);
The method executed by the task now is a while(true) loop, which delays for 100ms (not checking the token in the delay), and then calls the tokens ThrowCancellationIfRequested method. So, every 100ms this task will check the flag, and to exit it will throw an exception. When this happens, the exception is caught and the task's status is reported as Faulted.
Caught exception: The operation was canceled.
task1.Status == Faulted
Press any key to continue . . .
Now let's change one single line of code: 15. We are now passing in the cancellation token as a parameter to the Task.StartNew method. This associates the task with that token. If the method being run by the task throws an OperationAbortedException which contains this token (the case in this example), then TPL transitions the status of the task to Canceled instead of Faulted.
var f = new Func(
(interval, token) =>
{
while (true)
{
Task.Delay(100).Wait();
token.ThrowIfCancellationRequested();
}
}
);
var cts = new CancellationTokenSource();
var ct = cts.Token;
var task1 = Task.Factory.StartNew(() => f(100, ct), ct);
Task.Delay(500).Wait();
try
{
cts.Cancel();
task1.Wait();
}
catch (AggregateException ex)
{
Console.WriteLine("Caught exception {0}", ex.InnerExceptions[0].Message);
}
Console.WriteLine("task1.Status == {0}", task1.Status);
if (task1.Status == TaskStatus.RanToCompletion) Console.WriteLine("{0}", task1.Result);
Caught exception: A task was canceled.
task1.Status == Canceled
Press any key to continue . . .
The primary ramification of this is that if you want to have a task that responds to a cancellation event move to it's Canceled state, the task needs to throw an OperationAbortedException, which is the case when calling ThrowIfCancellationRequested method on the token and the IsCancellationRequested flag is true.
A second reason for passing the token to the StartNew method is that if the token already has its cancellation value set, then the task will not be started at all. The reasoning for this is that the token could have been passed in from elsewhere, and by the time this code tries to start other tasks the flag may have been set by another task. This prevents other tasks from being started and having to then cancel immediately, saving those resources from being unnecessarily consumed.
SUMMARY
Phew!! That was a lot, and this is just the one pattern of cancellation: polling. There are two more. Those will be covered in the next posts in the series. Fortunately, I can just show how they work without all these combinations of handing cancellation flags / throwing exceptions / try/catching. Those will all still apply, but be able to be assumed.
Also, here is a useful link to MSDN on cancellation for your reference.