ValueTask<TResult> Struktura

Definicja

Dostarcza typ wartości, który otacza Task<TResult> TResulti a, tylko jeden z nich jest używany.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))

Parametry typu

TResult

Wynik.The result.

Dziedziczenie
ValueTask<TResult>
Implementuje
IEquatable<ValueTask<TResult>>

Uwagi

Wystąpienie może być oczekiwane lub przekonwertowane Task<TResult> na użycie AsTask. ValueTask<TResult>A ValueTask<TResult> instance may either be awaited or converted to a Task<TResult> using AsTask. Wystąpienie może być oczekiwane tylko raz, a konsumenci mogą nie wywoływać GetAwaiter() do momentu zakończenia wystąpienia. ValueTask<TResult>A ValueTask<TResult> instance may only be awaited once, and consumers may not call GetAwaiter() until the instance has completed. Jeśli te ograniczenia są nieakceptowalne, przekonwertuj ValueTask<TResult> Task<TResult> na, wywołując AsTaskmetodę.If these limitations are unacceptable, convert the ValueTask<TResult> to a Task<TResult> by calling AsTask.

Następujące operacje nigdy nie powinny być wykonywane w ValueTask<TResult> przypadku wystąpienia:The following operations should never be performed on a ValueTask<TResult> instance:

  • Wiele razy czeka na wystąpienie.Awaiting the instance multiple times.
  • Wywoływanie AsTask wiele razy.Calling AsTask multiple times.
  • Użycie .Result lub.GetAwaiter().GetResult() czas operacji nie została jeszcze ukończona lub użycie ich wiele razy.Using .Result or .GetAwaiter().GetResult() when the operation hasn't yet completed, or using them multiple times.
  • Użycie więcej niż jednej z tych technik do korzystania z wystąpienia.Using more than one of these techniques to consume the instance.

Jeśli wykonasz dowolne z powyższych czynności, wyniki są niezdefiniowane.If you do any of the above, the results are undefined.

Metoda może zwrócić wystąpienie tego typu wartości, gdy istnieje najprawdopodobniej, że wynik operacji będzie dostępny synchronicznie, a kiedy oczekuje się, że koszt alokacji nowego Task<TResult> dla każdego wywołania będzie zabroniony.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.

Istnieją wady, które należy użyć ValueTask<TResult> zamiast. Task<TResult>There are tradeoffs to using a ValueTask<TResult> instead of a Task<TResult>. Na przykład, chociaż ValueTask<TResult> może pomóc uniknąć alokacji w przypadku, gdy pomyślne wyniki są dostępne synchronicznie, zawiera również wiele pól, a Task<TResult> jako typ referencyjny jest pojedynczym polem.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. Oznacza to, że zwrócenie ValueTask<TResult> z metody w wyniku kopiowania większej ilości danych.This means that returning a ValueTask<TResult> from a method results in copying more data. Oznacza to również, że jeśli metoda zwracająca ValueTask<TResult> wyjątek jest oczekiwana w metodzie asynchronicznej, komputer stanu dla tej metody asynchronicznej będzie większy, ponieważ musi przechowywać strukturę zawierającą wiele pól zamiast jednego odwołania.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.

W przypadku użycia innego niż zużywanie wyniku operacji asynchronicznej przy użyciu oczekiwania ValueTask<TResult> może prowadzić do bardziej zawiłeego modelu programowania, który wymaga więcej alokacji.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. Rozważmy na przykład metodę, która może zwrócić element Task<TResult> z buforowanym zadaniem jako wspólny wynik ValueTask<TResult>lub.For example, consider a method that could return either a Task<TResult> with a cached task as a common result or a ValueTask<TResult>. Jeśli odbiorca wyniku Task<TResult> chce użyć go jako metody, takiej jak WhenAll lub WhenAny, ValueTask<TResult> należy najpierw dokonać konwersji na element Task<TResult> using AsTask, co prowadzi do przydziału, który można było uniknąć, jeśli w Task<TResult> pierwszym miejscu użyto pamięci podręcznej.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.

W związku z tym domyślną opcją dla każdej metody asynchronicznej powinna być zwrócenie Task lub. Task<TResult>As such, the default choice for any asynchronous method should be to return a Task or Task<TResult>. Tylko wtedy, gdy analiza wydajności udowodni, że wartościowa ValueTask<TResult> powinna być używana zamiast. Task<TResult>Only if performance analysis proves it worthwhile should a ValueTask<TResult> be used instead of a Task<TResult>. Nieogólna wersja programu ValueTask nie jest zalecana w przypadku większości scenariuszy.The non generic version of ValueTask is not recommended for most scenarios. Właściwość powinna zostać użyta, aby ręcznie zakończyć działanie pojedyncze w przypadku, gdy metoda zwracająca się Task synchronicznie i pomyślnie. CompletedTaskThe 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.

Uwaga

Użycie ValueTask<TResult> tego typu jest obsługiwane począwszy od C# 7,0 i nie jest obsługiwane przez żadną wersję 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.

Konstruktory

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

Inicjuje nowe wystąpienie ValueTask<TResult> klasy IValueTaskSource<TResult> z obiektem, który reprezentuje operację.Initializes a new instance of the ValueTask<TResult> class with a IValueTaskSource<TResult> object that represents the operation.

ValueTask<TResult>(Task<TResult>)

Inicjuje nowe wystąpienie ValueTask<TResult> klasy przy użyciu dostarczonego zadania, które reprezentuje operację.Initializes a new instance of the ValueTask<TResult> class using the supplied task that represents the operation.

ValueTask<TResult>(TResult)

Inicjuje nowe wystąpienie ValueTask<TResult> klasy przy użyciu podanego wyniku operacji zakończonej powodzeniem.Initializes a new instance of the ValueTask<TResult> class using the supplied result of a successful operation.

Właściwości

IsCanceled

Pobiera wartość wskazującą, czy ten obiekt reprezentuje operację anulowaną.Gets a value that indicates whether this object represents a canceled operation.

IsCompleted

Pobiera wartość wskazującą, czy ten obiekt reprezentuje ukończoną operację.Gets a value that indicates whether this object represents a completed operation.

IsCompletedSuccessfully

Pobiera wartość wskazującą, czy ten obiekt reprezentuje pomyślnie ukończoną operację.Gets a value that indicates whether this object represents a successfully completed operation.

IsFaulted

Pobiera wartość wskazującą, czy ten obiekt reprezentuje niepowodzenie operacji.Gets a value that indicates whether this object represents a failed operation.

Result

Pobiera wynik.Gets the result.

Metody

AsTask()

Pobiera obiekt Task<TResult> , który reprezentuje ten ValueTask<TResult>element.Retrieves a Task<TResult> object that represents this ValueTask<TResult>.

ConfigureAwait(Boolean)

Konfiguruje await dla tej wartości.Configures an awaiter for this value.

CreateAsyncMethodBuilder()

Tworzy konstruktora metod do użycia z metodą asynchroniczną.Creates a method builder for use with an async method.

Equals(Object)

Określa, czy określony obiekt jest równy bieżącemu obiektowi.Determines whether the specified object is equal to the current object.

Equals(ValueTask<TResult>)

Określa, czy określony ValueTask<TResult> obiekt jest równy bieżącemu ValueTask<TResult> obiektowi.Determines whether the specified ValueTask<TResult> object is equal to the current ValueTask<TResult> object.

GetAwaiter()

Tworzy obiekt awaiter dla tej wartości.Creates an awaiter for this value.

GetHashCode()

Zwraca kod skrótu dla tego wystąpienia.Returns the hash code for this instance.

Preserve()

ValueTask<TResult> Pobiera, który może być używany w dowolnym momencie w przyszłości.Gets a ValueTask<TResult> that may be used at any point in the future.

ToString()

Zwraca ciąg, który reprezentuje bieżący obiekt.Returns a string that represents the current object.

Operatory

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

Porównuje dwie wartości dla równości.Compares two values for equality.

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

Określa, czy ValueTask<TResult> dwie wartości są różne.Determines whether two ValueTask<TResult> values are unequal.

Dotyczy