Task Cancelled By Manually-Thrown OperationCancelledException

[bgribaudo]

According to .Net Standard's documentation for Task.IsCancelled, there are three conditions when a task will report that it was cancelled. However, I'm observing cancelled tasks caused by a fourth condition. :-)

I'm trying to figure out whether what I'm observing is a bug with .Net or a case of incomplete documentation. :-)

Documentation

According to the docs, the three reasons a task may complete as cancelled are:

• Its CancellationToken was marked for cancellation before the task started executing,
• The task acknowledged the cancellation request on its already signaled CancellationToken by throwing an OperationCanceledException that bears the same CancellationToken.
• The task acknowledged the cancellation request on its already signaled CancellationToken by calling the ThrowIfCancellationRequested method on the CancellationToken.

All of these require that the Task is associated with a CancellationToken.

What I'm Seeing

Manually throwing an OperationCancelledException that is unassociated with a CancellationToken also results in the Task reporting that it was cancelled.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp2.0</TargetFramework>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <LangVersion>latest</LangVersion>
  </PropertyGroup>

</Project>

class Program
{
    static async Task Main(string[] args)
    {
        var task = Task.Run(() => throw new OperationCanceledException());
        try { await task; } catch { }
        Console.WriteLine(task.IsCanceled); // Outputs "True"
    }
}

Environment

Microsoft Visual Studio Professional 2017 Version 15.5.4 (VisualStudio.15.Release/15.5.4+27130.2024)
Microsoft .NET Framework Version 4.7.02556
dotNET Version 2.1.4

Question

Should a Task report that it's cancelled in this case? If it is, there's a documentation bug—and I can work on a documentation PR addressing it. If it shouldn't, it looks like there's a code bug somewhere.

[stephentoub]

Should a Task report that it's cancelled in this case? If it is, there's a documentation bug—and I can work on a documentation PR addressing it. If it shouldn't, it looks like there's a code bug somewhere.

The behavior is by-design and is specific to the specific overload of Task.Run you're using but may not realize you're using. It stems from a design decision we had to make as we introduced the async/await semantics into the existing Task APIs.

To help clarify things, let me change your code ever so slightly, simply by clarifying for the compiler which Task.Run overload should be used:

using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var task = Task.Run(new Action(() => throw new OperationCanceledException()));
        try { await task; } catch { }
        Console.WriteLine(task.IsCanceled); // Outputs "False"
    }
}

Contrary to your example, this outputs "False", with the task ending as Faulted rather than Canceled. Now I'll change it again:

using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var task = Task.Run(new Func<Task>(async () => throw new OperationCanceledException()));
        try { await task; } catch { }
        Console.WriteLine(task.IsCanceled); // Outputs "True"
    }
}

Here I'm explicitly using an async lambda and explicitly specifying Func<Task> as the delegate type. As I believe you'd expect, this now outputs "True", because that's the semantics of an OperationCanceledException going unhandled within an async method. But now consider this slight derivation:

using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var task = Task.Run(new Func<Task>(() => { throw new OperationCanceledException(); return Task.CompletedTask; }));
        try { await task; } catch { }
        Console.WriteLine(task.IsCanceled); // Outputs "True"
    }
}

This similarly outputs "True" even though it's no longer using async, because we didn't want the behaviors to be significantly different based on whether the Task-returning lambda was implemented with an async lambda or not, and to account for the possibility that an OperationCanceledException might be thrown from a delegate prior to actually doing the async logic.

Finally, we get to your example, and the best way to understand the behavior you're seeing is by looking at IntelliSense:

You can see from this image that the C# compiler is selecting the Func<Task> overload, based on how C#'s overload resolution works in conjunction with type inference in this specific case. So, your example is mapping to the Func<Task> overload that has this special behavior. You can see this behavior mentioned in the comment here:
https://github.com/dotnet/coreclr/blob/a53c01936eea8d5c61430dc2815c3e535d26ca84/src/mscorlib/src/System/Threading/Tasks/Task.cs#L5263-L5265

Hope that helps.

[bgribaudo]

@stephentoub, thank you for this detailed explanation of expected behavior. However, I'm still not sure how to reconcile it with the documentation quote in my original message which lists the various reasons a task reports itself as cancelled.

The only reason having to do with OperationCancelledException is:

The task acknowledged the cancellation request on its already signaled CancellationToken by throwing an OperationCanceledException that bears the same CancellationToken.

In the (expected) behavior you described, the task reports itself as cancelled regardless of whether OperationCancelledException bears the CancellationToken that's associated with the task. However, the quote above requires that the token in the exception match the token associated with the task, so it doesn't seem to apply here.

Is the behavior you described another (separate) reason why a task will report itself as cancelled? Something like:

If Task executes a Func<> which throws an OperationCancelledException, regardless of the CancellationToken associated with the exception.

[tarekgh]

@stephentoub do you think we need to add some clarification to the doc? if so, I can log a new doc issue.

[stephentoub]

The Task.IsCanceled list is incomplete; there are other reasons a task might end in the canceled state. For example:

Task a = ...;
Task b = a.ContinueWith(..., TaskContinuationOptions.OnlyOnFaulted);

If a completes successfully, then b will be canceled, and there's no cancellation token provided to ContinueWith.

If Task executes a Func<> which throws an OperationCancelledException, regardless of the CancellationToken associated with the exception.

This really isn't about Tasks in general; it's about that specific overload of Task.Run. That same behavior doesn't manifest for Task.Factory.StartNew, for example, or for other overloads of Task.Run.

do you think we need to add some clarification to the doc? if so, I can log a new doc issue.

I think it's fine to update the docs with additional info.

[tarekgh]

I have logged the doc issue https://github.com/dotnet/docs/issues/4756 and I am going to close this one.

[bgribaudo]

Thanks, @tarekgh!