Clarify ValueTask consumption guidance#12751
Open
YNan-varamor wants to merge 1 commit into
Open
Conversation
dotnet-policy-service
Bot
added
the
community-contribution
Contributor
|
Tagging subscribers to this area: @dotnet/area-system-threading-tasks |
Author
|
@dotnet-policy-service agree |
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Updates the ValueTask / ValueTask<T> reference docs to better reflect real-world behavior (Task-backed vs pooled IValueTaskSource) and to soften “never do this” guidance into conditional guidance based on provider support.
Changes:
- Clarify that multiple awaits may appear to work for Task/synchronous-backed
ValueTaskinstances, but pooledIValueTaskSource-backed instances should be treated as single-consumption unless documented otherwise. - Update the “should never be performed” list to “should not be performed unless supported by provider” for both
ValueTaskandValueTask<T>.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| xml/System.Threading.Tasks/ValueTask`1.xml | Refines ValueTask<T> remarks about repeated awaits and IValueTaskSource<T> pooling semantics. |
| xml/System.Threading.Tasks/ValueTask.xml | Mirrors the same guidance updates for non-generic ValueTask. |
|
|
||
| ## Remarks | ||
| A `ValueTask` instance may either be awaited or converted to a <xref:System.Threading.Tasks.Task> using <xref:System.Threading.Tasks.ValueTask.AsTask*>. A `ValueTask` instance may only be awaited once, and consumers may not call <xref:System.Threading.Tasks.ValueTask.GetAwaiter> until the instance has completed. If these limitations are unacceptable, convert the `ValueTask` to a <xref:System.Threading.Tasks.Task> by calling <xref:System.Threading.Tasks.ValueTask.AsTask*>. | ||
| A `ValueTask` instance may either be awaited or converted to a <xref:System.Threading.Tasks.Task> using <xref:System.Threading.Tasks.ValueTask.AsTask*>. If the instance wraps a <xref:System.Threading.Tasks.Task> or a synchronous result, multiple awaits might succeed. However, a `ValueTask` instance can also be backed by a pooled <xref:System.Threading.Tasks.Sources.IValueTaskSource>, so consumers should treat an arbitrary `ValueTask` as single-consumption unless the provider explicitly documents support for multiple consumption. Consumers may not call <xref:System.Threading.Tasks.ValueTask.GetAwaiter> until the instance has completed. If these limitations are unacceptable, convert the `ValueTask` to a <xref:System.Threading.Tasks.Task> by calling <xref:System.Threading.Tasks.ValueTask.AsTask*>. |
Comment on lines
+93
to
+95
| A <xref:System.Threading.Tasks.ValueTask`1> instance may either be awaited or converted to a <xref:System.Threading.Tasks.Task`1> using <xref:System.Threading.Tasks.ValueTask`1.AsTask*>. If the instance wraps a <xref:System.Threading.Tasks.Task`1> or a synchronous result, multiple awaits might succeed. However, a <xref:System.Threading.Tasks.ValueTask`1> instance can also be backed by a pooled <xref:System.Threading.Tasks.Sources.IValueTaskSource`1>, so consumers should treat an arbitrary <xref:System.Threading.Tasks.ValueTask`1> as single-consumption unless the provider explicitly documents support for multiple consumption. Consumers may not read <xref:System.Threading.Tasks.ValueTask`1.Result> until the instance has completed. If these limitations are unacceptable, convert the <xref:System.Threading.Tasks.ValueTask`1> to a <xref:System.Threading.Tasks.Task`1> by calling <xref:System.Threading.Tasks.ValueTask`1.AsTask*>. | ||
|
|
||
| The following operations should never be performed on a <xref:System.Threading.Tasks.ValueTask`1> instance: | ||
| The following operations should not be performed on a <xref:System.Threading.Tasks.ValueTask`1> instance unless the provider explicitly documents that they are supported: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #12704.
This updates the
ValueTaskandValueTask<TResult>remarks so the guidance is less absolute and reflects the backing-source distinction:Taskor a synchronous result may allow repeated awaitsValueTaskinstances should still be treated as single-consumption because they may be backed by pooledIValueTaskSourceAsTaskremains the documented path when multiple consumption is neededValidation:
git diff --checkDisclosure: I used OpenAI Codex to implement and verify this documentation update.