ValueTask<TResult> 構造体


Task<TResult>TResult をラップする値の型を提供します。使用するのは一方だけです。Provides a value type that wraps a Task<TResult> and a TResult, only one of which is used.

generic <typename TResult>
public value class ValueTask : IEquatable<System::Threading::Tasks::ValueTask<TResult>>
public struct ValueTask<TResult> : IEquatable<System.Threading.Tasks.ValueTask<TResult>>
type ValueTask<'Result> = struct
Public Structure ValueTask(Of TResult)
Implements IEquatable(Of ValueTask(Of TResult))



結果。The result.



AsTaskを使用して、ValueTask<TResult> インスタンスを待機するか、Task<TResult> に変換することができます。A ValueTask<TResult> instance may either be awaited or converted to a Task<TResult> using AsTask. ValueTask<TResult> インスタンスは1回だけ待機できます。また、インスタンスが完了するまでコンシューマーが GetAwaiter() を呼び出すことはできません。A ValueTask<TResult> instance may only be awaited once, and consumers may not call GetAwaiter() until the instance has completed. これらの制限が許容されない場合は、AsTaskを呼び出して、ValueTask<TResult>Task<TResult> に変換します。If these limitations are unacceptable, convert the ValueTask<TResult> to a Task<TResult> by calling AsTask.

ValueTask<TResult> インスタンスでは、次の操作を実行しないでください。The following operations should never be performed on a ValueTask<TResult> instance:

  • インスタンスを複数回待機しています。Awaiting the instance multiple times.
  • AsTask を複数回呼び出す。Calling AsTask multiple times.
  • 操作がまだ完了していない場合、または操作を複数回使用する場合は、.Result または .GetAwaiter().GetResult() を使用します。Using .Result or .GetAwaiter().GetResult() when the operation hasn't yet completed, or using them multiple times.
  • インスタンスを使用するために、これらの手法の1つ以上を使用します。Using more than one of these techniques to consume the instance.

上記のいずれかを実行すると、結果は未定義になります。If you do any of the above, the results are undefined.

メソッドは、この値型のインスタンスを返すことがあります。その操作の結果が同期的に使用可能になる可能性があり、呼び出しごとに新しい Task<TResult> を割り当てるコストが膨大になることが予想される場合があります。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.

Task<TResult>ではなく ValueTask<TResult> を使用すると、トレードオフが発生します。There are tradeoffs to using a ValueTask<TResult> instead of a Task<TResult>. たとえば、ValueTask<TResult> は、正常に実行された結果が同期的に使用可能な場合、割り当てを回避するのに役立ちますが、参照型として Task<TResult> は1つのフィールドであるのに対し、複数のフィールドが含まれています。For example, while a ValueTask<TResult> can help avoid an allocation in the case where the successful result is available synchronously, it also contains multiple fields, whereas a Task<TResult> as a reference type is a single field. これは、メソッドから ValueTask<TResult> を返すと、より多くのデータがコピーされることを意味します。This means that returning a ValueTask<TResult> from a method results in copying more data. また、ValueTask<TResult> を返すメソッドが非同期メソッド内で待機している場合は、1つの参照ではなく複数のフィールドを含む構造体を格納する必要があるため、その非同期メソッドのステートマシンのサイズは大きくなります。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 multiple fields instead of a single reference.

Await を使用した非同期操作の結果を使用する以外の用途では、より多くの割り当てを必要とする、より複雑なプログラミングモデルに ValueTask<TResult> ことがあります。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. たとえば、共通の結果または ValueTask<TResult>としてキャッシュされたタスクを含む Task<TResult> を返すメソッドがあるとします。For example, consider a method that could return either a Task<TResult> with a cached task as a common result or a ValueTask<TResult>. 結果のコンシューマーが WhenAllWhenAnyなどのメソッドで Task<TResult> として使用する場合は、まず Task<TResult> を使用して ValueTask<TResult>AsTaskに変換し、キャッシュされた Task<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 AsTask, leading to an allocation that would have been avoided if a cached Task<TResult> had been used in the first place.

そのため、任意の非同期メソッドの既定の選択肢は、Task または Task<TResult>を返す必要があります。As such, the default choice for any asynchronous method should be to return a Task or Task<TResult>. パフォーマンス分析では、Task<TResult>ではなく ValueTask<TResult> 使用する必要があることが証明されている場合にのみ使用してください。Only if performance analysis proves it worthwhile should a ValueTask<TResult> be used instead of a Task<TResult>. ValueTask の非ジェネリックバージョンは、ほとんどのシナリオでは推奨されません。The non generic version of ValueTask is not recommended for most scenarios. Task を返すメソッドが同期的に正常に完了した場合に、正常に完了したシングルトンを戻すには、CompletedTask プロパティを使用する必要があります。The CompletedTask property should be used to hand back a successfully completed singleton in the case where a method returning a Task completes synchronously and successfully.


ValueTask<TResult> 型の使用はC# 7.0 以降でサポートされており、Visual Basic のどのバージョンでもサポートされていません。The use of the ValueTask<TResult> type is supported starting with C# 7.0, and is not supported by any version of Visual Basic.


ValueTask<TResult>(IValueTaskSource<TResult>, Int16)

操作を表す ValueTask<TResult> オブジェクトを使用して、IValueTaskSource<TResult> クラスの新しいインスタンスを初期化します。Initializes a new instance of the ValueTask<TResult> class with a IValueTaskSource<TResult> object that represents the operation.


操作を表す指定されたタスクを使用して、ValueTask<TResult> クラスの新しいインスタンスを初期化します。Initializes a new instance of the ValueTask<TResult> class using the supplied task that represents the operation.


成功した操作の指定された結果を使用して、ValueTask<TResult> クラスの新しいインスタンスを初期化します。Initializes a new instance of the ValueTask<TResult> class using the supplied result of a successful operation.



このオブジェクトが取り消された操作を表すかどうかを示す値を取得します。Gets a value that indicates whether this object represents a canceled operation.


このオブジェクトが完了した操作を表すかどうかを示す値を取得します。Gets a value that indicates whether this object represents a completed operation.


このオブジェクトが正常に完了した操作を表すかどうかを示す値を取得します。Gets a value that indicates whether this object represents a successfully completed operation.


このオブジェクトが失敗した操作を表すかどうかを示す値を取得します。Gets a value that indicates whether this object represents a failed operation.


結果を取得します。Gets the result.



この Task<TResult> を表す ValueTask<TResult> オブジェクトを取得します。Retrieves a Task<TResult> object that represents this ValueTask<TResult>.


この値の awaiter を構成します。Configures an awaiter for this value.


非同期のメソッドで使用するためにメソッドのビルダーを作成します。Creates a method builder for use with an async method.


指定されたオブジェクトが現在のオブジェクトと等しいかどうかを判定します。Determines whether the specified object is equal to the current object.


指定した ValueTask<TResult> オブジェクトが、現在の ValueTask<TResult> オブジェクトと等しいかどうかを判断します。Determines whether the specified ValueTask<TResult> object is equal to the current ValueTask<TResult> object.


この値の awaiter を作成します。Creates an awaiter for this value.


このインスタンスのハッシュ コードを返します。Returns the hash code for this instance.


将来のある時点で使用される可能性のある ValueTask<TResult> を取得します。Gets a ValueTask<TResult> that may be used at any point in the future.


現在のオブジェクトを表す string を返します。Returns a string that represents the current object.


Equality(ValueTask<TResult>, ValueTask<TResult>)

2 つの値が等しいかどうかを比較します。Compares two values for equality.

Inequality(ValueTask<TResult>, ValueTask<TResult>)

2 つの ValueTask<TResult> 値が等しくないかどうかを判断します。Determines whether two ValueTask<TResult> values are unequal.