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))

Параметры типа

TResult

Результат.The result.

Наследование
ValueTask<TResult>
Реализации
IEquatable<ValueTask<TResult>>

Комментарии

Экземпляр может быть либо ожидающим, либо преобразованным Task<TResult> в using AsTask. ValueTask<TResult>A ValueTask<TResult> instance may either be awaited or converted to a Task<TResult> using AsTask. Экземпляр можно ожидать только один раз, и потребители могут не вызываться GetAwaiter() до завершения экземпляра. ValueTask<TResult>A ValueTask<TResult> instance may only be awaited once, and consumers may not call GetAwaiter() 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.
  • Использование более чем одного из этих методов для использования экземпляра.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> то время как ссылочный тип является одним полем.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> значение, ожидает в асинхронном методе, конечный автомат для этого асинхронного метода будет больше, так как он должен хранить структуру, содержащую несколько полей, а не одну ссылку.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. Свойство следует использовать для обратного успешного завершения одноэлементного элемента в случае, когда метод, возвращающий завершение, Task синхронно и успешно завершается. 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.

Примечание

Использование 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>(Task<TResult>)

Инициализирует новый экземпляр класса ValueTask<TResult>, используя указанную задачу, которая представляет операцию.Initializes a new instance of the ValueTask<TResult> class using the supplied task that represents the operation.

ValueTask<TResult>(TResult)

Инициализирует новый экземпляр класса ValueTask<TResult>, используя указанный результат успешной операции.Initializes a new instance of the ValueTask<TResult> class using the supplied result of a successful operation.

Свойства

IsCanceled

Возвращает значение, указывающее, представляет ли этот объект отмененную операцию.Gets a value that indicates whether this object represents a canceled operation.

IsCompleted

Возвращает значение, указывающее, представляет ли этот объект завершенную операцию.Gets a value that indicates whether this object represents a completed operation.

IsCompletedSuccessfully

Возвращает значение, указывающее, представляет ли этот объект успешно завершенную операцию.Gets a value that indicates whether this object represents a successfully completed operation.

IsFaulted

Возвращает значение, указывающее, представляет ли этот объект операцию, завершившуюся ошибкой.Gets a value that indicates whether this object represents a failed operation.

Result

Возвращает результат.Gets the result.

Методы

AsTask()

Получает объект Task<TResult>, который представляет ValueTask<TResult>.Retrieves a Task<TResult> object that represents this ValueTask<TResult>.

ConfigureAwait(Boolean)

Настраивает объект типа awaiter для этого значения.Configures an awaiter for this value.

CreateAsyncMethodBuilder()

Создает построитель метода для использования с асинхронным методом.Creates a method builder for use with an async method.

Equals(Object)

Определяет, равен ли заданный объект текущему объекту.Determines whether the specified object is equal to the current object.

Equals(ValueTask<TResult>)

Определяет, равен ли заданный объект ValueTask<TResult> текущему объекту ValueTask<TResult>.Determines whether the specified ValueTask<TResult> object is equal to the current ValueTask<TResult> object.

GetAwaiter()

Создает объект типа awaiter для этого значения.Creates an awaiter for this value.

GetHashCode()

Возвращает хэш-код данного экземпляра.Returns the hash code for this instance.

Preserve()

Получает объект ValueTask<TResult>, который можно будет использовать в любой момент в будущем.Gets a ValueTask<TResult> that may be used at any point in the future.

ToString()

Возвращает строку, представляющую текущий объект.Returns a string that represents the current object.

Операторы

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

Сравнивает два значения на предмет их равенства.Compares two values for equality.

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

Определяет неравенство двух значений ValueTask<TResult>.Determines whether two ValueTask<TResult> values are unequal.

Применяется к