Continuation tasks in .NET TPL: make continuation conditional

Tasks in .NET TPL make it easy to assign tasks that should run upon the completion of a certain task. You can also specify on what condition the continuation task should run.

We’ll need a basic object with a single property:

public class Series
{
	public int CurrentValue
	{
		get;
		set;
	}
}

Declare and start a task that increases the CurrentValue in a loop and return the Series. This task is called the antecedent task in a chain of tasks.

Task<Series> motherTask = Task.Factory.StartNew<Series>(() =>
{
	Series series = new Series();
	for (int i = 0; i < 5000; i++)
	{
		series.CurrentValue++;
	}
	return series;
});

You can create other tasks that will continue upon the completion of the antecedent task. The default value is that the continuation task will be scheduled to start when the preceding task has completed. However, the Task constructor – and the task factory – let’s you supply a TaskContinuationOptions enumeration.

This is how you declare a default continuation task:

Task<int> firstContinuationTask
	= motherTask.ContinueWith<int>((Task<Series> antecedent) =>
	{
		Console.WriteLine("First continuation task reporting series value: {0}", antecedent.Result.CurrentValue);
		return antecedent.Result.CurrentValue * 2;
	});

The first continuation task reads the Series object built by the antecedent, the “mother” task. It prints out the CurrentValue of the Series. The continuation task also returns an integer: the series value multiplied by two.

You can extend this declaration as follows:

Task<int> firstContinuationTask
	= motherTask.ContinueWith<int>((Task<Series> antecedent) =>
	{
		Console.WriteLine("First continuation task reporting series value: {0}", antecedent.Result.CurrentValue);
		return antecedent.Result.CurrentValue * 2;
	}, TaskContinuationOptions.OnlyOnRanToCompletion);

Note the extra TaskContinuationOptions.OnlyOnRanToCompletion parameter. As the name implies it will only run if the antecedent has completed successfully: it has not been cancelled and has not thrown an unhandled exception.

Other important enumeration values:

• None: the default value, the continuation will run when the antecedent completes
• NotOnRanToCompletion: the opposite of OnlyOnRanToCompletion, i.e. only run if antecedent has been cancelled or has thrown an unhandled exception
• OnlyOnFaulted: if antecedent has thrown an unhandled exception
• NotOnFaulted: if antecedent has not thrown any unhandled exceptions
• OnlyOnCancelled: if antecedent has been cancelled
• NotOnCancelled: if antecedent has not been cancelled

Let’s declare a second continuation task:

Task secondContinuationTask
	= firstContinuationTask.ContinueWith((Task<int> antecedent) =>
	{
		Console.WriteLine("Second continuation task reporting series value: {0}", antecedent.Result);
	}, TaskContinuationOptions.NotOnRanToCompletion);

Note that it’s enough to start the first task, which we did with Task.Factory.StartNew. The continuation tasks will be scheduled automatically.

Provided that the mother task completes and the first continuation also completes the second continuation will not run due to the specified NotOnRanToCompletion option.

View the list of posts on the Task Parallel Library here.

Continuation tasks in .NET TPL: continuation with different result type

Tasks in .NET TPL make it easy to assign tasks that should run upon the completion of a certain task.

We’ll need a basic object with a single property:

public class Series
{
	public int CurrentValue
	{
		get;
		set;
	}
}

Declare a task that increases the CurrentValue in a loop and return the Series. This task is called the antecedent task.

Task<Series> motherTask = Task.Factory.StartNew<Series>(() =>
{
	Series series = new Series();
	for (int i = 0; i < 10000; i++)
	{
		series.CurrentValue++;
	}
	return series;
});

Declare the continuation task where we also use the antecedent as method parameter. Note that the return type of the continuation task can be different from that of the antecedent:

Task continuationTask = motherTask.ContinueWith((Task previousTask) =>
{
	Console.WriteLine("Interim value: {0}", previousTask.Result.CurrentValue);
	return previousTask.Result.CurrentValue * 2;
});

Read the result of the continuation task:

Console.WriteLine("Final value: {0}", continuationTask.Result);

View the list of posts on the Task Parallel Library here.

Waiting for one in a group of Tasks to complete in .NET C#

You can use the static WaitAny() method to wait for one of many tasks to complete. The method blocks until one of the tasks has finished. It returns the array index of the task that has finished first.

WaitAny() has a number of overloaded versions which follow the same pattern as the Wait() method we saw in this post. If you use one of the overloaded methods then an array index of -1 means that the time period has expired or the cancellation token has been cancelled before any of the tasks could complete.

Example:

Build the cancellation token:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
CancellationToken cancellationToken = cancellationTokenSource.Token;

Construct two – or more- tasks:

Task taskOne = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 10; i++)
	{
		cancellationToken.ThrowIfCancellationRequested();
		Console.WriteLine(i);
		cancellationToken.WaitHandle.WaitOne(1000);
	}
	Console.WriteLine("Task 1 complete");
}, cancellationToken);

Task taskTwo = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 5; i++)
	{
		cancellationToken.ThrowIfCancellationRequested();
		Console.WriteLine(i);
		cancellationToken.WaitHandle.WaitOne(500);
	}
	Console.WriteLine("Task 2 complete");
}, cancellationToken);

Wait for the first one:

int arrayIndex = Task.WaitAny(taskOne, taskTwo);

Note that a task provided to the WaitAny method is considered “complete” if either of the following is true:

• The task finishes its work
• The task is cancelled
• The task has thrown an exception

If one of the tasks throws an exception then WaitAny will also throw one.

View the list of posts on the Task Parallel Library here.

Waiting for a group of Tasks to complete in .NET C#

You can use the static WaitAll() method to wait for more than one task to complete. If you use the WaitAll(tasks[]) version then WaitAll only returns if all tasks in the task array have completed.

WaitAll() has a number of overloaded versions which follow the same pattern as the Wait() method we saw in this post.

Example:

Build the cancellation token:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
CancellationToken cancellationToken = cancellationTokenSource.Token;

Construct two – or more- tasks:

Task taskOne = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 10; i++)
	{
		cancellationToken.ThrowIfCancellationRequested();
		Console.WriteLine(i);
		cancellationToken.WaitHandle.WaitOne(1000);
	}
	Console.WriteLine("Task 1 complete");
}, cancellationToken);

Task taskTwo = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 5; i++)
	{
		cancellationToken.ThrowIfCancellationRequested();
		Console.WriteLine(i);
		cancellationToken.WaitHandle.WaitOne(500);
	}
	Console.WriteLine("Task 2 complete");
}, cancellationToken);

Wait for them:

Task.WaitAll(taskOne, taskTwo);

Note that a task provided to the WaitAll method is considered “complete” if either of the following is true:

• The task finishes its work
• The task is cancelled
• The task has thrown an exception

If one of the tasks throws an exception then WaitAll will also throw one.

View the list of posts on the Task Parallel Library here.

Wait for a single Task in .NET C#: the Wait() method

Waiting for a single Task to finish is as easy as calling the Wait() method or one of its overloaded versions:

Wait();
Wait(CancellationToken);
Wait(int);
Wait(TimeSpan);
Wait(int, CancellationToken);

In short from top to bottom:

• Wait until the Task completes, is cancelled or throws an exception
• Wait until the cancellation token is cancelled or the task completes, is cancelled or throws an exception
• Wait for ‘int’ amount of milliseconds to pass OR for the task to complete, be cancelled or throw an exception, whichever happens first
• Wait for ‘TimeSpan’ amount of time to pass OR for the task to complete, be cancelled or throw an exception, whichever happens first
• Wait for ‘int’ amount of milliseconds to pass, for the cancellation token to be cancelled, OR for the task to complete, be cancelled or throw an exception, whichever happens first

Example:

Construct the cancellation token:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
CancellationToken cancellationToken = cancellationTokenSource.Token;

Start a task:

Task task = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 10; i++)
	{
		cancellationToken.ThrowIfCancellationRequested();
		Console.WriteLine(i);
		cancellationToken.WaitHandle.WaitOne(1000);
	}
}, cancellationToken);

We can then wait for the task to complete:

task.Wait();

If we are impatient then we specify a maximum amount of milliseconds for the task to complete otherwise it is abandoned:

task.Wait(2000);

The other overloads work in a similar manner.

View the list of posts on the Task Parallel Library here.

Suspending a Task using SpinWait in .NET C#

You may want to put a Task to sleep for some time. You might want to check the state of an object before continuing. The Task continues after the sleep time.

One way to solve this is using the Thread.SpinWait method since the Task library uses .NET threading support in the background.

First construct your cancellation token:

CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();
CancellationToken cancellationToken = cancellationTokenSource.Token;

Use this token in the constructor of the task:

Task task = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 100000; i++)
	{
		Thread.SpinWait(10000);
		Console.WriteLine(i);
		cancellationToken.ThrowIfCancellationRequested();
	}
}, cancellationToken);

You can use the cancellation token to interrupt the task:

cancellationTokenSource.Cancel();

We looked at Thread.Sleep and the WaitOne method in the previous posts on TPL. With those two techniques the thread that’s currently performing the task gives up its turn while sleeping. This gives a chance to other threads to do something. With spin waiting it’s different as the thread does not give up its turn.

The integer argument in SpinWait indicates an iteration. It is the number of times that a tight CPU loop will be performed. The exact amount of sleep time will depend on the speed of the CPU so it’s not some well defined period of time. Therefore spin waiting doesn’t stop using the CPU.

Bear in mind these limitations and use SpinWait with care – if ever.

View the list of posts on the Task Parallel Library here.

Cancel multiple Tasks at once in .NET C#

You cannot directly interrupt a Task in .NET while it’s running. You can do it indirectly through the CancellationTokenSource object. This object has a CancellationToken property which must be passed into the constructor of the Task:

CancellationTokenSource cancellationTokenSource	= new CancellationTokenSource();
CancellationToken cancellationToken = cancellationTokenSource.Token;

You can re-use the same token in the constructor or several tasks:

Task firstTask = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 100000; i++)
	{
		cancellationToken.ThrowIfCancellationRequested();
		Console.WriteLine(i);
	}
}, cancellationToken);

Task secondTask = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < int.MaxValue; i++)
	{
		cancellationToken.ThrowIfCancellationRequested();
		Console.WriteLine(i);
	}
}, cancellationToken);

We simply count up to 100000 in the Task bodies. We’re using the ThrowIfCancellationRequested() method of the cancellation token, I’ll explain shortly what it does.

You can cancel both tasks by calling the Cancel() method of the token like this:

cancellationTokenSource.Cancel();

Note that this method only signals the wish to cancel a task. .NET will not actively interrupt the task, you’ll have to monitor the status through the IsCancellationRequested property. It is your responsibility to stop the task. In this example we’ve used the built-in “convenience” method ThrowIfCancellationRequested() which throws an OperationCanceledException which is a must in order to correctly acknowledge the cancellation. If you forget this step then the task status will not be set correctly. Once the task has been requested the stop it cannot be restarted.

If you need to do something more substantial after cancellation, such as a resource cleanup, then you can monitor cancellation through the IsCancellationRequested and throw the OperationCanceledException yourself:

for (int i = 0; i < 100000; i++)
{
	if (token.IsCancellationRequested)
	{
		Console.WriteLine("Task cancellation requested");
		throw new OperationCanceledException(token);
	}
	else
	{
		Console.WriteLine(i);
	}
}

View the list of posts on the Task Parallel Library here.

Monitoring Task cancellation in .NET C# using a Wait handle

You cannot directly interrupt a Task in .NET while it’s running. You can do it indirectly through the CancellationTokenSource object. This object has a CancellationToken property which must be passed into the constructor of the Task:

CancellationTokenSource cancellationTokenSource	= new CancellationTokenSource();
CancellationToken cancellationToken = cancellationTokenSource.Token;

The cancellation token can be used as follows:

// create the task
Task task = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 100000; i++)
	{
		if (cancellationToken.IsCancellationRequested)
		{
			Console.WriteLine("Task cancelled, must throw exception.");
			throw new OperationCanceledException(cancellationToken);
		}
		else
		{
			Console.WriteLine(i);
		}
	}
}, cancellationToken);

We simply count up to 100000 in the Task body. Note the IsCancellationRequested property of the token. We monitor within the loop whether the task has been cancelled.

The cancellation token has a property called WaitHandle which has a method called WaitOne(). This method blocks until the Cancel() method is called on the token source provided in the Task constructor. It can be used by setting up another Task which calls the WaitOne method which blocks until the first Task has been cancelled:

Task secondTask = Task.Factory.StartNew(() =>
	{
		cancellationToken.WaitHandle.WaitOne();
		Console.WriteLine("WaitOne called.");
	});

You can cancel the task by calling the Cancel() method of the token like this:

cancellationTokenSource.Cancel();

Note that this method only signals the wish to cancel a task. .NET will not actively interrupt the task, you’ll have to monitor the status through the IsCancellationRequested property. It is your responsibility to stop the task. In this example we throw an OperationCanceledException which is a must in order to correctly acknowledge the cancellation. If you forget this step then the task status will not be set correctly. Once the task has been requested the stop it cannot be restarted.

If that’s all you want to do, i.e. throw an OperationCanceledException, then there’s a shorter version:

cancellationToken.ThrowIfCancellationRequested();

This will perform the cancellation check and throw the exception in one step. The loop can thus be simplified as follows:

Task task = Task.Factory.StartNew(() =>
{
	for (int i = 0; i < 100000; i++)
	{
		//shorthand
        	cancellationToken.ThrowIfCancellationRequested();

		Console.WriteLine(i);
	}
}, cancellationToken);

View the list of posts on the Task Parallel Library here.