Value​Task<​TResult> Struct

Definition

Provides a value type that wraps a Task{TResult} and a TResult, only one of which is used.

public struct ValueTask<TResult> : IEquatable<System.Threading.Tasks.ValueTask<TResult>>
Type Parameters
TResult

The result.

Inheritance
ValueTask<TResult>
Implements
IEquatable<ValueTask<TResult>>

Remarks

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 Task<TResult> for each call will be prohibitive.

There are tradeoffs to using a ValueTask<TResult> instead of a Task<TResult>. For example, while a ValueTask<TResult> can help avoid an allocation in the case where the successful result is available synchronously, it also contains two fields, whereas a Task<TResult> 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 ValueTask<TResult> 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.

For uses other than consuming the result of an asynchronous operation using await, ValueTask<TResult> can lead to a more convoluted programming model that requires more allocations. For example, consider a method that could return either a Task<TResult> with a cached task as a common result or a ValueTask<TResult>. If the consumer of the result wants to use it as a Task<TResult> in a method like WhenAll or WhenAny, the ValueTask<TResult> must first be converted to a Task<TResult> using <xref:System.Threading.Tasks.ValueTask{TResult}.AsTask%2A>, leading to an allocation that would have been avoided if a cached Task<TResult> had been used in the first place.

As such, the default choice for any asynchronous method should be to return a Task or Task<TResult>. Only if performance analysis proves it worthwhile should a ValueTask<TResult> be used instead of a Task<TResult>. There is no non-generic version of ValueTask<TResult>, as the CompletedTask property may be used to hand back a successfully completed singleton in the case where a method returning a Task completes synchronously and successfully.

Note

The use of the type is supported starting with C# 7, and is not supported by any version of Visual Basic.

Constructors

Value​Task<​TResult>(​Task<​TResult>)

Initializes a new instance of the ValueTask{TResult} class using the supplied task that represents the operation.

Value​Task<​TResult>(​TResult)

Initializes a new instance of the ValueTask{TResult} class using the supplied result of a successful operation.

Properties

Is​Canceled

Gets a value that indicates whether this object represents a canceled operation.

Is​Completed

Gets a value that indicates whether this object represents a completed operation.

Is​Completed​Successfully

Gets a value that indicates whether this object represents a successfully completed operation.

Is​Faulted

Gets a value that indicates whether this object represents a failed operation.

Result

Gets the result.

Methods

As​Task()

Retrieves a Task{TResult} object that represents this ValueTask{TResult}.

Configure​Await(​Boolean)

Configures an awaiter for this value.

Create​Async​Method​Builder()

Creates a method builder for use with an async method.

Equals(​Object)

Determines whether the specified object is equal to the current object.

Equals(​Value​Task<​TResult>)

Determines whether the specified ValueTask{TResult} object is equal to the current ValueTask{TResult} object.

Get​Awaiter()

Creates an awaiter for this value.

Get​Hash​Code()

Returns the hash code for this instance.

To​String()

Returns a string that represents the current object.

Operators

Equality(​Value​Task<​TResult>, ​Value​Task<​TResult>)

Compares two values for equality.

Inequality(​Value​Task<​TResult>, ​Value​Task<​TResult>)

Determines whether two ValueTask{TResult} values are unequal.