What is ValueTask, when should you use it instead of Task, and what rules must callers follow?

1. The struct's shape

public readonly struct ValueTask<TResult>
{
    internal readonly object? _obj;        // null, Task<TResult>, or IValueTaskSource<TResult>
    internal readonly TResult? _result;    // used when _obj is null (synchronous result)
    internal readonly short _token;        // identifies the operation for an IValueTaskSource
    internal readonly bool _continueOnCapturedContext;
}

The awaiter checks _obj: null → return _result; Task<T> → behave like a task; IValueTaskSource<T> → call GetStatus(token), OnCompleted(...), GetResult(token).

2. IValueTaskSource<T> and token checks

source (reused object)
  op #1: token = 5 -> ValueTask(source, 5) -> consumer awaits -> GetResult(5) -> source resets
  op #2: token = 6 -> ValueTask(source, 6) -> ...
old ValueTask(source, 5) awaited again -> GetResult(5) on a source now at token 6
  -> InvalidOperationException (if checked) or wrong data (if the implementation doesn't check)

ManualResetValueTaskSourceCore<T> (a mutable struct helper) implements the bookkeeping: version/token, continuation, result, RunContinuationsAsynchronously. Sockets (SocketAsyncEventArgs-based AwaitableSocketAsyncEventArgs), System.IO.Pipelines and Channel<T> readers use this pattern.

3. A safe fast-path pattern

public ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken ct = default)
{
    if (_buffered.Length > 0)
    {
        int n = CopyFromBuffer(buffer.Span);
        return new ValueTask<int>(n);              // synchronous, no allocation
    }
    return ReadSlowAsync(buffer, ct);              // async path (async ValueTask<int> method)
}

private async ValueTask<int> ReadSlowAsync(Memory<byte> buffer, CancellationToken ct)
{
    await FillBufferAsync(ct).ConfigureAwait(false);
    return CopyFromBuffer(buffer.Span);
}

Splitting the fast path into a non-async method also avoids state machine overhead entirely when synchronous.

4. Consuming on a hot path

ValueTask<int> vt = reader.ReadAsync(buf, ct);
int n = vt.IsCompletedSuccessfully ? vt.Result : await vt;   // read once, either branch

This is the only legitimate case of touching .Result: after confirming completion, and never touching vt again.

5. Analysers

6. Version notes

7. Try it yourself

1. Benchmark Task<int> vs ValueTask<int> for a cache hit with [MemoryDiagnoser]; note allocated bytes.
2. Repeat for a method that always awaits Task.Yield(); observe no saving.
3. Add [AsyncMethodBuilder(typeof(PoolingAsyncValueTaskMethodBuilder<>))] to the always-async version and re-measure.
4. Await a Channel<int>.Reader.ReadAsync() result twice and see what happens.
5. Enable CA2012 and introduce a double-await to see the warning.
6. Implement a tiny IValueTaskSource<int> using ManualResetValueTaskSourceCore<int> and reuse it for 10 operations.

using System.Collections.Concurrent;

var repo = new PriceRepository();

// Correct: await once.
decimal p1 = await repo.GetPriceAsync("ABC");

// Need it twice or in WhenAll? Convert once.
Task<decimal> t = repo.GetPriceAsync("XYZ").AsTask();
await Task.WhenAll(t, Task.Delay(10));
Console.WriteLine($"{p1} {t.Result}");

public sealed class PriceRepository
{
    private readonly ConcurrentDictionary<string, decimal> _cache = new();

    public ValueTask<decimal> GetPriceAsync(string sku)
    {
        // Fast path: synchronous, no allocation.
        if (_cache.TryGetValue(sku, out var price))
            return ValueTask.FromResult(price);

        return new ValueTask<decimal>(LoadAsync(sku));
    }

    private async Task<decimal> LoadAsync(string sku)
    {
        await Task.Delay(20); // stands in for a database call
        decimal price = sku.Length * 10m;
        _cache[sku] = price;
        return price;
    }
}

Wrong usage to avoid:

ValueTask<decimal> vt = repo.GetPriceAsync("ABC");
var a = await vt;
var b = await vt; // undefined behaviour with pooled sources