Skip to content

Commit e33effe

Browse files
MSDN-WhiteKnightBillWagner
authored andcommitted
Update ValueTask`1.xml (#2756)
Documentation mentioned that ValueTask contains 2 fields. As of current CoreFX version, ValueTask contains 4 instance fields, not 2 (https://github.com/dotnet/corefx/blob/master/src/Common/src/CoreLib/System/Threading/Tasks/ValueTask.cs#L416). I don't think it is needed to specify exact amount of fields, so i suggested to reword this paragraph.
1 parent 9dddfe7 commit e33effe

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
@@ -58,7 +58,7 @@ If you do any of the above, the results are undefined.
5858
5959
A method may return an instance of this value type when it's likely that the result of its operation will be available synchronously, and when it's expected to be invoked so frequently that the cost of allocating a new <xref:System.Threading.Tasks.Task%601> for each call will be prohibitive.
6060
61-
There are tradeoffs to using a <xref:System.Threading.Tasks.ValueTask%601> instead of a <xref:System.Threading.Tasks.Task%601>. For example, while a <xref:System.Threading.Tasks.ValueTask%601> can help avoid an allocation in the case where the successful result is available synchronously, it also contains two fields, whereas a <xref:System.Threading.Tasks.Task%601> as a reference type is a single field. This means that a method call returns two fields worth of data instead of one, which is more data to copy. It also means, that if a method that returns a <xref:System.Threading.Tasks.ValueTask%601> is awaited within an async method, the state machine for that async method will be larger, because it must store a struct containing two fields instead of a single reference.
61+
There are tradeoffs to using a <xref:System.Threading.Tasks.ValueTask%601> instead of a <xref:System.Threading.Tasks.Task%601>. For example, while a <xref:System.Threading.Tasks.ValueTask%601> can help avoid an allocation in the case where the successful result is available synchronously, it also contains multiple fields, whereas a <xref:System.Threading.Tasks.Task%601> as a reference type is a single field. This means that returning a <xref:System.Threading.Tasks.ValueTask%601> from a method results in copying more data. It also means, that if a method that returns a <xref:System.Threading.Tasks.ValueTask%601> is awaited within an async method, the state machine for that async method will be larger, because it must store a struct containing multiple fields instead of a single reference.
6262
6363
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.
6464

0 commit comments

Comments
 (0)