Task.WaitAsync description is wrong

[raffaeler]

Type of issue

Other (describe below)

Description

https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.waitasync?view=net-10.0#system-threading-tasks-task-waitasync(system-timespan-system-timeprovider)

The description states: "Gets a Task that will complete when this Task completes or when the specified timeout expires."
This information is wrong."

When a timeout argument is specified and the timeout expires, the Task.WaitAsync always throw a TimeoutException.

Please note that the description is wrong for all the other overloads.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.waitasync?view=net-10.0#system-threading-tasks-task-waitasync(system-timespan-system-timeprovider)

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Threading.Tasks/Task.xml

Document Version Independent Id

4975978e-14a9-88e1-bec2-ea632d3c08d7

Platform Id

4fa165a2-05cd-c7d8-44d5-b6b3d0d66862

Article author

@dotnet-bot

[tannergooding]

The description is not incorrect. A task is considered completed (i.e. Task.IsCompleted returns true) if it is one of RanToCompletion (i.e. success), Faulted (i.e. threw an exception) or Canceled

As can be seen from the source (https://source.dot.net/#System.Private.CoreLib/src/libraries/System.Private.CoreLib/src/System/Threading/Tasks/Task.cs,69846ca916c930be) the method simply defers to the centralized helper, which then wraps a TimeoutException in a task if the timeout is 0 and otherwise creates a CancellationPromise which simply does TrySetException when the timeout is reached.

Any behavior on an exception being raised is not from the method itself, but by the calling of Wait() or an equivalent such as GetAwaiter().GetResult() which will propagate it back onto the thread that did this call. Calling these is a side effect of doing await task: https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/exception-handling-task-parallel-library

If you never await the task, then it will never throw which can be trivial seen from the following code:

var task = Task.Delay(1000).WaitAsync(TimeSpan.FromMilliseconds(0));
Console.WriteLine($"IsCompleted: {task.IsCompleted}");
Console.WriteLine($"IsFaulted: {task.IsFaulted}");
await task;

This propagation can also be suppressed by using ConfigureAwait

[raffaeler]

Thanks Tanner, your explanation is of course impeccable.
I find the description misleading anyway because it provides an information that is not specific to this method, but of the TPL in general.
I would instead underline the difference between awaiting with WaitAsync and WhenAny with a Task.Delay in the array.

[tannergooding]

I find the description misleading anyway because it provides an information that is not specific to this method, but of the TPL in general.

Not sure what you mean. The documentation describes exactly the behavior of the method in question and does so correctly.

You had a misunderstanding related to something that is rather a general feature of async/await. It is unfeasible and untenable for us to document how await x works on every single possible async API, or even link to a doc covering that concept (which is notably C# specific; other languages can work differently if they so choose).

The docs related to how await x works belongs with the language docs around that keyword (where they are present). Likewise other APIs that do cause propagation (like Wait()) do correctly document that they can surface such exceptions already, so it all remains consistent and correct with regards to what can raise given exceptions.

[raffaeler]

It is unfeasible and untenable for us to document how await x works on every single possible async API

I meant the opposite, sorry if I am not able to explain it clearly but English is not my mother tongue.
I do not believe the description is sufficiently clear for this specific case. I am not asking to explain the async/await behavior for every API.

The reason why I found it misleading is because, from the description I would assume a behavior similar to the one the user would obtain when awaiting a task and a task.delay using whenany which was the standard pattern used before waitasync.

The fun part is that I hit this docs because the code generated by Opus did not take into account the TimeoutException while I know it would be thrown. I was surprised and when I read the docs I found it misleading.

Anyway, feel free to close this. Clarifications are meant to broadly help the dev community and nothing else.

[tannergooding]

Before this gets closed, I guess I'm still confused as to what you're finding confusing or misleading here?

Maybe you could give an example of what you expect https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.waitasync?view=net-10.0#system-threading-tasks-task-waitasync(system-timespan-system-timeprovider) to show?

---

The description covers

Gets a Task that will complete when this Task completes or when the specified timeout expires.

Which is exactly how this API behaves. The only time a TimeoutException is raised is when you await the task this method returns (or otherwise call an API like Task.Wait() which documents itself as propagating up that exception).

That is, this API behaves exactly as documented and any additional behavior is from calling await task, which is how all task returning APIs behave (as its tied to the await, not the task).

[raffaeler]

I am very well aware that await is the moment where I could get an exception. I don´t believe that it is necessary to repeat this in the docs.

Anyway, here are the requested overload descriptions:

WaitAsync(TimeSpan)

• Returns a proxy task that mirrors the original task, but faults with a TimeoutException if the original task does not finish within the specified timeout.

WaitAsync(TimeSpan, CancellationToken)

• Returns a proxy task that faults with a TimeoutException if the timeout expires, or throws an OperationCanceledException if the token is triggered, before the original task finishes.

WaitAsync(TimeSpan, TimeProvider)

• Identical to WaitAsync(TimeSpan), but uses the provided TimeProvider abstraction to measure the timeout duration (useful for testing).

WaitAsync(TimeSpan, TimeProvider, CancellationToken)

• Imposes both a timeout (measured by the provided TimeProvider) and cancellation monitoring on the wait operation.

This should give an idea, but of course my terminology/expression (already fixed by AI) could not necessarily be optimal as English is not my primary language.

HTH