Add Task.WaitAsync methods

[stephentoub]

Fixes #47525
Fixes #27722

Note that #47525 api-approved a different surface area, but we will rediscuss next week instead using the revised proposal, which this PR implements. If we instead decide to stick with what was approved, I'll replace this with stephentoub@a91eb11, which has the same guts but different public APIs exposing it. For now, I'm marking it no merge until the revised surface area is approved.

[ghost]

Tagging subscribers to this area:
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Fixes #47525
Fixes #27722

Note that #47525 api-approved a different surface area, but we will rediscuss next week instead using the revised proposal, which this PR implements. If we instead decide to stick with what was approved, I'll replace this with stephentoub@a91eb11, which has the same guts but different public APIs exposing it. For now, I'm marking it no merge until the revised surface area is approved.

Author:	stephentoub
Assignees:	-
Labels:	area-System.Threading.Tasks
Milestone:	6.0.0

[dotnet-issue-labeler]

Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, to please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

[eiriktsarpalis]

Implementation LGTM, but I'm also having second thoughts about the ValueTask methods now.

[eiriktsarpalis]

Pinging @dotnet/ncl since the change touches networking product code as well.

[stephentoub]

but I'm also having second thoughts about the ValueTask methods now.

Yup ;-)

[adamsitnik]

LGTM, all I've found were really minor nits ;)

Thank you @stephentoub !

[davidfowl]

Waiting for the WaitAsync().Wait() bugs to be filed 🤣

[paulomorgado]

This seems more akin the WhenAny and WhenAll.

It should be called just When.

/cc @stephentoub

[stephentoub]

We explored lots of options and names. I think "When" is strictly worse than where we landed.

[paulomorgado]

Wait is from the "old days" before async/await.

Why is When strictly worse than WaitAsync?

[stephentoub]

Wait is from the "old days" before async/await.

It's not. SemaphoreSlim, for example, has Wait and WaitAsync methods.

"When" only shows up in the static WhenAny and WhenAll, where is about one or all of the arguments completing. That's not the case here, where it's an instance method that's about waiting for the instance, just asynchronously, just as with SemaphoreSlim.WaitAsync, and with the wait curtailed by the arguments, just as with Wait. "When" makes it sound like the operation won't complete until the timeout or cancellation is requested, which is not the case.

[paulomorgado]

SemaphoreSlim.WaitAsync is the asynchronous version of SemaphoreSlim.Wait.

My understanding of the general guidance is that Task returning methods should be suffixed Async, except if they already have methods suffixed Async, like WebClient. In that case, they should be suffixed TaskAsync.

The exceptions to this rule are methods operating on Task itself. That´s why there's Task.Run instead of Task.RunAsync. And Task.WhenAll, and Task.WhenAny.

[stephentoub]

SemaphoreSlim.WaitAsync is the asynchronous version of SemaphoreSlim.Wait.

That's exactly the same case here.

The exceptions to this rule are methods operating on Task itself. That´s why there's Task.Run instead of Task.RunAsync. And Task.WhenAll, and Task.WhenAny.

Those are all statics. This is not. It is the asynchronous version of the synchronous Wait, just as with SemaphoreSlim. Async isn't used in the statics on task because it's deemed redundant in that context; it's not here.

[paulomorgado]

Got it!

[ghost]

I know I'm coming in late here, but @stephentoub any chance you can provide a control option to honor custom TaskSchedulers? Presently ConfigureAwait(false) suppresses both executioncontext capture and taskscheduler capture. Hoping some day that the default will permit custom schedulers for applications that need some control over thread scheduling (e.g. to implement quotas)