Skip to content

Commit 44a6ee7

Browse files
baj22BillWagner
authored andcommitted
Update ValueTask`1.xml (#2073)
* Update ValueTask`1.xml There is a non-generic version of ValueTask. The documentation was misleading. * Update ValueTask`1.xml Added suggested alternative. * add brackets around xref Once the build finishes, I'll merge it.
1 parent 4af83e7 commit 44a6ee7

File tree

1 file changed

+1
-1
lines changed

1 file changed

+1
-1
lines changed

xml/System.Threading.Tasks/ValueTask`1.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ There are tradeoffs to using a <xref:System.Threading.Tasks.ValueTask%601> inste
5050
5151
For uses other than consuming the result of an asynchronous operation using await, <xref:System.Threading.Tasks.ValueTask%601> can lead to a more convoluted programming model that requires more allocations. For example, consider a method that could return either a <xref:System.Threading.Tasks.Task%601> with a cached task as a common result or a <xref:System.Threading.Tasks.ValueTask%601>. If the consumer of the result wants to use it as a <xref:System.Threading.Tasks.Task%601> in a method like <xref:System.Threading.Tasks.Task.WhenAll%2A> or <xref:System.Threading.Tasks.Task.WhenAny%2A>, the <xref:System.Threading.Tasks.ValueTask%601> must first be converted to a <xref:System.Threading.Tasks.Task%601> using <xref:System.Threading.Tasks.ValueTask%601.AsTask%2A>, leading to an allocation that would have been avoided if a cached <xref:System.Threading.Tasks.Task%601> had been used in the first place.
5252
53-
As such, the default choice for any asynchronous method should be to return a <xref:System.Threading.Tasks.Task> or <xref:System.Threading.Tasks.Task%601>. Only if performance analysis proves it worthwhile should a <xref:System.Threading.Tasks.ValueTask%601> be used instead of a <xref:System.Threading.Tasks.Task%601>. There is no non-generic version of <xref:System.Threading.Tasks.ValueTask%601>, as the <xref:System.Threading.Tasks.Task.CompletedTask> property may be used to hand back a successfully completed singleton in the case where a method returning a <xref:System.Threading.Tasks.Task> completes synchronously and successfully.
53+
As such, the default choice for any asynchronous method should be to return a <xref:System.Threading.Tasks.Task> or <xref:System.Threading.Tasks.Task%601>. Only if performance analysis proves it worthwhile should a <xref:System.Threading.Tasks.ValueTask%601> be used instead of a <xref:System.Threading.Tasks.Task%601>. The non generic version of <xref:System.Threading.Tasks.ValueTask> is not recommended for most scenarios. The <xref:System.Threading.Tasks.Task.CompletedTask> property should be used to hand back a successfully completed singleton in the case where a method returning a <xref:System.Threading.Tasks.Task> completes synchronously and successfully.
5454
5555
> [!NOTE]
5656
> The use of the <xref:System.Threading.Tasks.ValueTask%601> type is supported starting with C# 7.0, and is not supported by any version of Visual Basic.

0 commit comments

Comments
 (0)