To make up for the missing two intermediate combinations, developers may pass CancellationToken.None (or default(CancellationToken)) for the cancellationToken parameter and/or null for the progress parameter.
If it is expected that every usage of the TAP method should utilize cancellation and/or progress, the overloads that don’t accept the relevant parameter may be omitted.
If multiple overloads of a TAP method are exposed to make cancellation and/or progress optional, the overloads that don’t support cancellation and/or progress should behave as if they’d passed CancellationToken.None for cancellation and null for progress to the overload that does support these.
Implementing the Task-based Asynchronous Pattern
In the .NET Framework 4.5, the C# and Visual Basic compilers are capable of implementing the TAP. Any method attributed with the async keyword (Async in Visual Basic) is considered to be an asynchronous method, and the compiler will perform the necessary transformations to implement the method asynchronously using the TAP. Such a method should return either a Task or a Task. In the case of the latter, the body of the function should return a TResult, and the compiler will ensure that this result is made available through the resulting Task. Similarly, any exceptions that go unhandled within the body of the method will be marshaled to the output task, causing the resulting Task to end in the Faulted state; the one exception to this is if an OperationCanceledException (or derived type) goes unhandled, such that the resulting Task will end in the Canceled state.
Developers may implement the TAP manually, just as the compiler does or with greater control over exactly how the method is implemented. The compiler relies on public surface area exposed from the System.Threading.Tasks namespace (and supporting types in the System.Runtime.CompilerServices namespace built on top of System.Threading.Tasks), functionality also available to developers directly. For more information, see the following section on Workloads. When implementing a TAP method manually, a developer must be sure to complete the resulting Task when the represented asynchronous operation completes.
It is often useful to manually implement the TAP pattern with the core logic for the implementation implemented in a compiler-generated implementation. This is the case, for example, when arguments should be verified outside of a compiler-generated asynchronous method in order for the exceptions to escape to the method’s direct caller rather than being exposed through the Task, e.g.
public Task MethodAsync(string input)
if (input == null) throw new ArgumentNullException("input");
Another case where such delegation is useful is when a “fast path” optimization can be implemented that returns a cached task.
Both compute-bound and I/O-bound asynchronous operations may be implemented as TAP methods. However, when exposed publicly from a library, TAP implementations should only be provided for workloads that involve I/O-bound operations (they may also involve computation, but should not be purely computation). If a method is purely compute-bound, it should be exposed only as a synchronous implementation; a consumer may then choose whether to wrap an invocation of that synchronous method into a Task for their own purposes of offloading the work to another thread and/or to achieve parallelism.
The Task class is ideally suited to representing computationally-intensive operations. By default, it utilizes special support within the .NET ThreadPool in order to provide efficient execution, while also providing a great deal of control over when, where, and how asynchronous computations execute.
There are several ways compute-bound tasks may be generated.
In .NET 4, the primary way for launching a new compute-bound task is the TaskFactory.StartNew method, which accepts a delegate (typically an Action or a Func) to be executed asynchronously. If an Action is provided, a Task is returned to represent the asynchronous execution of that delegate. If a Func is provided, a Task is returned. Overloads of StartNew exist that accept CancellationToken, TaskCreationOptions, and TaskScheduler, all of which provide fine-grained control over the task’s scheduling and execution. A factory instance that targets the current task scheduler is available as a static property off of the Task class, e.g. Task.Factory.StartNew(…).
In .NET 4.5, the Task type exposes a static Run method as a shortcut to StartNew and which may be used to easily launch a compute-bound task that targets the ThreadPool. As of .NET 4.5, this is the preferred mechanism for launching a compute-bound task; StartNew should only be used directly when more fine-grained control is required over its behavior.
The Task type exposes constructors and a Start method. These may be used if construction must be done separate from scheduling. (As previously mentioned in this document, public APIs must only return tasks that have already been started.)
The Task type exposes multiple overloads of ContinueWith. This method creates a new task that will be scheduled when another task completes. Overloads exist that accept CancellationToken, TaskContinuationOptions, and TaskScheduler, all of which provide fine-grained control over the continuation task’s scheduling and execution.
The TaskFactory class provides ContinueWhenAll and ContinueWhenAny methods. These methods create a new task that will be scheduled when all of or any of a supplied set of tasks completes. As with ContinueWith, support exists for controlling the scheduling and execution of these tasks.
Compute-bound tasks are special with regards to cancellation, as the system can prevent actually executing a scheduled task if a cancellation request is received prior to the execution starting. As such, if a CancellationToken is provided, in addition to possibly passing that token into the asynchronous code which may monitor the token, the token should also be provided to one of the previously mentioned routines (e.g. StartNew, Run) so that the Task runtime may also monitor the token.
Consider an asynchronous method that renders an image. The body of the task can poll the cancellation token such that, while rendering is occurring, the code may exit early if a cancellation request arrives. In addition, we also want to prevent doing any rendering if the cancellation request occurs prior to rendering starting:
Compute-bound tasks will end in a Canceled state if at least one of the following conditions is true:
The CancellationToken provided as an argument to the creation method (e.g. StartNew, Run) has cancellation requested prior to the Task transitioning to the TaskStatus.Running state.
An OperationCanceledException goes unhandled within the body of such a Task, that OperationCanceledException contains as its CancellationToken property the same CancellationToken passed into the Task, and that CancellationToken has had cancellation requested.
If another exception goes unhandled within the body of the Task, that Task will end in the Faulted state, and any attempts to wait on the task or access its result will result in an exception being thrown.
Tasks that should not be directly backed by a thread for the entirety of their execution are created using the TaskCompletionSource type. TaskCompletionSource exposes a Task property which returns an associated Task instance. The life-cycle of this task is controlled by methods exposed from the TaskCompletionSource instance, namely SetResult, SetException, SetCanceled, and their TrySet* variants.
Consider the need to create a task that will complete after a specified duration of time. This could, for example, be useful in UI scenarios where the developer wants to delay an activity for a period of time. The .NET System.Threading.Timer class already provides the ability to asynchronously invoke a delegate after a specified period of time, and using TaskCompletionSource we can put a Task façade on the timer, e.g.
In the .NET Framework 4.5, the Task.Delay method is provided for this purpose. Such a method could now be used inside of another asynchronous method to, for example, implement an asynchronous polling loop:
There is no non-generic counterpart to TaskCompletionSource. However, Task derives from Task, and thus the generic TaskCompletionSource can be used for I/O-bound methods that simply return a Task by utilizing a source with a dummy TResult (Boolean is a good default choice, and if a developer is concerned about a consumer of the Task downcasting it to a Task, a private TResult type may be used). For example, the previously shown Delay method was developed to return the current time along with the resulting Task. If such a result value is unnecessary, the method could have instead been coded as follows (note the change of return type and the change of argument to TrySetResult):
public static Task Delay(int millisecondsTimeout)
var tcs = new TaskCompletionSource();
new Timer(self =>
Mixed Compute- and I/O-bound Tasks
Asynchronous methods are not limited to just compute-bound or I/O-bound operations, but may represent a mixture of the two. In fact, it is often the case that multiple asynchronous operations of different natures are composed together into larger mixed operations. For example, consider the previously shown RenderAsync method which performed a computationally-intensive operation to render an image based on some input ImageData. This ImageData could come from a Web service which we asynchronously access:
public async Task DownloadDataAndRenderImageAsync(
var imageData = await DownloadImageDataAsync(cancellationToken);
This example also demonstrates how a single CancellationToken may be threaded through multiple asynchronous operations. More on this topic is discussed in the cancellation usage section later in this document.