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.



インスタンスは、 ValueTask<TResult> を使用して待機するか、を使用してに変換することができ Task<TResult> AsTask ます。A ValueTask<TResult> instance may either be awaited or converted to a Task<TResult> using AsTask. ValueTask<TResult>インスタンスを待機できるのは1回だけです。また、 Result インスタンスが完了するまでコンシューマーを読み取ることはできません。A ValueTask<TResult> instance may only be awaited once, and consumers may not read Result until the instance has completed. これらの制限が許容されない場合は、を呼び出して、をに変換し ValueTask<TResult> Task<TResult> AsTask ます。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.

の代わりにを使用すると、トレードオフが発生 ValueTask<TResult> Task<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. たとえば、 Task<TResult> 共通の結果またはとしてキャッシュされたタスクを含むを返すメソッドがあるとし ValueTask<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>. 結果のコンシューマーがやなどのメソッドでをとして使用する場合は、まず Task<TResult> WhenAll WhenAny ValueTask<TResult> を使用してをに変換する必要があり Task<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>. パフォーマンス分析では、ではなくを使用する必要があることが証明されている場合にのみ ValueTask<TResult> 使用 Task<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. CompletedTaskを返すメソッドが Task 同期的かつ正常に完了した場合に、正常に完了したシングルトンを戻すには、プロパティを使用する必要があります。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.


パラメーターなしのコンストラクターまたは構文 (ゼロ初期化構造体) で作成されたインスタンスは、 default(ValueTask<TResult>) の結果を使用して、同期的に正常に完了した操作を表し default(TResult) ます。An instance created with the parameterless constructor or by the default(ValueTask<TResult>) syntax (a zero-initialized structure) represents a synchronously, successfully completed operation with a result of default(TResult).


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

操作を表す IValueTaskSource<TResult> オブジェクトを使用して、ValueTask<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.



この ValueTask<TResult> を表す Task<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.


現在のオブジェクトを表す文字列を返します。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.