Add ValueTask factory members

[stephentoub]

Fixes #27960
cc: @tarekgh

[ghost]

Tagging subscribers to this area: @tarekgh
Notify danmosemsft if you want to be subscribed.

[Dotnet-GitSync-Bot]

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.

[tarekgh]

@stephentoub

System\IO\Compression\enc\BrotliStream.Compress.cs(79,20): error CS0173: (NETCORE_ENGINEERING_TELEMETRY=Build) Type of conditional expression cannot be determined because there is no implicit conversion between 'System.Threading.Tasks.ValueTask<int>' and 'System.Threading.Tasks.ValueTask'

[stephentoub]

Thanks. Will fix.

[bgrainger]

This member feels confusing from an API standpoint. Per https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask?view=net-5.0:

The following operations should never be performed on a ValueTask instance:

• Awaiting the instance multiple times.

Although it's actually legal, it feels like using ValueTask.CompletedTask leads immediately to violating the above "should never" guideline. If I return this "instance" from my own method, won't my method's callers be awaiting the "same" instance multiple times and violating the rule? (Saying it's a by-value copy and they're actually different instances doesn't resolve the problem, as copying a ValueTask doesn't provide an exception to the current set of rules.)

If it's argued that this is a special case and can be treated differently, that just makes the ValueTask rules more difficult to comply with, as they can no longer be applied consistently.

[stephentoub]

Fair question, but that assumes it's returning the same instance each time you invoke the getter. Think of it as a member you're invoking and it's giving you back an already completed task you can use once. It's not special in that way. I can invoke Stream.ReadAsync and use the returned ValueTask once. I can invoke ValueTask.FromException and use the returned ValueTask once. ValueTask.CompletedTask is the same.

[bgrainger]

Thanks for the response; that's a fair interpretation.

I was going to argue that it is then inconsistent with Task.CompletedTask, which returns the same instance for efficiency, but then I read the docs and saw that "Repeated attempts to retrieve this property value may not always return the same instance.", so TIL.